OpenOffice.org Users' Guides, Training, and More www.getopenoffice.org
J2EE: The Big Picture - Dating Design Patterns: What the Gang of Four Didn't Tell You - Dating Power Tools: Simple Stuff That Works - She'll Love It: The Guys' Guide to Giving Great Gifts
Originally posted by Solveig Laura Haugland:
As I understand Agility generally (fuzzily), one of the assumptions is that documenting as you go along isn't a good idea since the docs are always out of date and wrong. I'm on board with that.
I also understand that on some projects the users are bidden to fiddle with the prototype and give feedback as things go along, which means that there isn't necessarily a solid UI or set of specs for the techwriters to document to.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
OpenOffice.org Users' Guides, Training, and More www.getopenoffice.org
J2EE: The Big Picture - Dating Design Patterns: What the Gang of Four Didn't Tell You - Dating Power Tools: Simple Stuff That Works - She'll Love It: The Guys' Guide to Giving Great Gifts
Originally posted by Solveig Laura Haugland:
Re the dev docs, I was making an invisible leap in my own head. Techwriters often use the tech docs as a basis for their own docs; thus fewer docs change the standard process for what TWs often do.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Ilja Preuss:
Yes - they would rely more on direct, face-to-face communication, and on the actual, running system.
At work, we have one TW (it's a small company). Last month we enhanced our nightly build so that it automatically deploys the system to our inhouse webstart server. That way, the TW can always work on the most current version. (It's quite cool, IMHO )
OpenOffice.org Users' Guides, Training, and More www.getopenoffice.org
J2EE: The Big Picture - Dating Design Patterns: What the Gang of Four Didn't Tell You - Dating Power Tools: Simple Stuff That Works - She'll Love It: The Guys' Guide to Giving Great Gifts
Originally posted by Solveig Laura Haugland:
I hope he/she knows how great that is.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
Originally posted by Solveig Laura Haugland:
That is VERRRRRRRRRRY cool. Oh my god.
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Stan James:
I'm curious about your spot in life. As tech writer, who is your audience? What's your medium - dynamic web docs you can change every day or printed manuals that must be "perfect" for the next commercial release? Those things could seriously affect how happy you are with your agile developer buddies down the hall, no?
The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Originally posted by Stan James:
I'm curious about your spot in life. As tech writer, who is your audience? What's your medium - dynamic web docs you can change every day or printed manuals that must be "perfect" for the next commercial release? Those things could seriously affect how happy you are with your agile developer buddies down the hall, no?
OpenOffice.org Users' Guides, Training, and More www.getopenoffice.org
J2EE: The Big Picture - Dating Design Patterns: What the Gang of Four Didn't Tell You - Dating Power Tools: Simple Stuff That Works - She'll Love It: The Guys' Guide to Giving Great Gifts
Originally posted by Ilja Preuss:
I guess I have to remember that story. Wonder wether it works that way on other girls, too...
OpenOffice.org Users' Guides, Training, and More www.getopenoffice.org
J2EE: The Big Picture - Dating Design Patterns: What the Gang of Four Didn't Tell You - Dating Power Tools: Simple Stuff That Works - She'll Love It: The Guys' Guide to Giving Great Gifts
Originally posted by Solveig Laura Haugland:
[QB]Hi Scott,
SLH: Speaking of the shelf-feet of manuals mentioned in another topic, I'm hoping to learn something agile techniques and technical writing. (I've been in the techwriting/training field for 13 years.) As I understand Agility generally (fuzzily), one of the assumptions is that documenting as you go along isn't a good idea since the docs are always out of date and wrong. I'm on board with that.
Scott: That's an issue, but the real problem is that the more docs you write, the more you need to keep updated, review, ensure traceability between, ... You really want to remain as lean as possible.
SLH: I also understand that on some projects the users are bidden to fiddle with the prototype and give feedback as things go along, which means that there isn't necessarily a solid UI or set of specs for the techwriters to document to.
Scott: Agile Modeling (www.agilemodeling.com) includes a practice called Active Stakeholder Participation which says that stakeholders (including users) can and should be members of the team. They provide information, make decisions, and can even be active members of your modeling and maybe even development efforts. To accomplish this you need tools and techniques that they can use, one of the reasons behind AM's Use the Simplest Tools concept.
SLH: I have a few questions about how agility affects docs and doc processes:
- Generally, what is the effect of agile techniques on the techwriters who work with the agile programmers, and the docs they produce?
Scott: They should become active members of the team. They likely will be doing far more than tech writing though as they should strive to become generalizing specialists (http://www.agilemodeling.com/essays/generalizingSpecialists.htm). The Agile documentation essay (http://www.agilemodeling.com/essays/agileDocumentation.htm) should prove to be of interest and there is even a book by that name (http://www.amazon.com/exec/obidos/ASIN/0470856173/ambysoftinc) now.
- Can techwriters apply agile development techniques to techwriting?
Scott: Absolutely, if you choose to.
- Is there something else techwriters can do besides try to help make the UI as logical and easy as possible, thus requiring less documentation? (I've helped create a couple systems that simply suck data out of the program or database into a usable UI; they were very successful and a huge load of work off the TW team.)
Scott: I'm a firm believer that all developers should have solid UI skills, although unfortunately few people seem to understand the importance of this. In the 3rd Edition of The Object Primer (www.ambysoft.com/theObjectPrimer.html), due out in March, I include an entire chapter on the subject. It's irresponsible that most writers who cover software design to ignore UI issues, IMHO. I think we need to raise the bar a bit.
- Do you advocate documentation being started, and when should it be finished, in a world where all managers always want the software shipped the second QA signs off on it?
Scott: Take a look at the AD essay. Documentation should be treated just like any other requirement -- it should be done in priority order. Sounds like your managers need to be educated a bit. ;-)
- Any other advice?
Scott: Just keep learning and trying new stuff.
-Scott
<a href="http://www-306.ibm.com/software/rational/bios/ambler.html" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="http://www.ambysoft.com/books/refactoringDatabases.html" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
Don't get me started about those stupid light bulbs. |