Appropriate Technical Documentation

What is the appropriate level of technical documentation for a project? Is it...

I think that StrongConcepts that might have evolved over time in your project are a good candidate for the Intelligent Selection mentioned above (see also DesignDocumentation). --JorritWiersma

In SoftwareDevelopmentAsaCooperativeGame, AlistairCockburn says...

"The real target of the manifesto is to set up how we view all the work products we produce. I have yet to interview a project in which they were kept consistent (with the exception of ChryslerComprehensiveCompensation, which, knowing that, deliberately set the number of intermediate work products needing maintenance to zero). Most people I have met bemoan this situation. I wish to establish that it is normal and proper and should be dealt with in a certain way.

"The only real purpose of the intermediate work products is to help the team make their next move in the game. They have no intrinsic value (they may have competitive value as intellectual property). They are not important of models of reality. They serve only to help the team create the final work product. ..."

See "AgileDocumentation" by ScottAmbler, Copyright 2001 at http://www.agilemodeling.com/essays/agileDocumentation.htm

This is a Very Good Article. --DaveSmith

See Also:

and (off topic):

The more I think about this "documentation" word, the more loathsome and upsetting it becomes.

"Documentation" is masturbation. Doing "documentation" is easy, it's almost a habit for some people. There's a certain fleeting, self-centered pleasure in doing it. It occupies your time. It won't make you go blind, but it's nothing to be proud of. And it's of no value to anyone else.

Writing user guides is not "documentation". Neither is writing educational material. These activities produce outputs that are, yes, documents. But these are documents of significant, and sometimes lasting, value. Alistair's intermediate work products are exactly that, and more like calisthenics than the five-knuckle shuffle. The stuff produced by "documentation" is no use to anyone, goes stale almost immediately, and can leave a lasting, and highly unpleasent, stain on anything it comes into contact with.

So let's stop using the damn word. If a thing is worth producing, it's worth naming with a right name that reflects that value. In current usage, the "D" word says everything and knothing about the useful and useless all together at the same time. Let's produce only valuable things, and make sure they're recognised as such, with clear, explicit nomenclature. -- KeithBraithwaite

Hey, Keith, get a grip. Yes, documentation is a word that is much abused, but that doesn't give you an excuse for intentionally "misunderestimating" -- to quote a Famous Person -- the use of docs when applied appropriately. As a few Wikizens have pointed out, documents need to be targeted at a particular audience to be useful and meaningful. Not only that, but they need to be written by writers, not engineers who can't write and who can't even speel there weigh out of a wet paper bag. By the way -- the next time I need to ask for an API to read and some yahoo tells me to look at the code I'm gonna punch his silly lights out.

[NOTE: did you happen to detect a reflection of your own comments here? If you come back to mellow out your vitriol above please feel free to refactor this little section out. And in the future, try to chill out before hitting the Save button. -- MartySchrader]

When the developers recognize the value of the intermediate work products ("technical documentation") to their ongoing development and maintenance efforts, <...which is rare, I admit. ;-> then keeping the documents up-to-date is not that difficult. You have to focus on the forms of documentation that have real value, and you need highly motivated developers. I've worked on two projects that immediately spring to mind, where this approach was successful:

SalesKit? Software: ('96 to '98)

In spite of the usual CrisisManagement?, FireFighting and short-term thinking typical of small startups, we managed to create a number of useful diagrams, of varying lifetimes, that served to drive our development process. The most successful, the "Status/State Diagram," was a custom mix of StateTransitionDiagram and DataFlowDiagram notations, illustrating how messages flowed within and between the client and server systems. Created for one small development team, to replace a spreadsheet that wasn't meeting our needs, this one page diagram became indispensable to all design and development discussion (for that subsystem), and was adopted by operations, customer support, and training. This diagram was kept up-to-date and used heavily for the life of the system.

When I left, we were making progress on "Class Diagrams" of our own unique form -- a cross between Booch ClassDiagrams and StructureCharts? (typical of Modular procedural styles). (In my absence, I'd expect them to revert to chaos, however. ;-)

Training system in Dallas, TX: (late '80s)

CategoryDocumentation

EditText of this page (last edited July 6, 2006) or FindPage with title or text search