Developers Don't Write Documentation

An article titled Developers Don't Write Documentation can be found at OpenXource. It is written with some wit and is worth reading. As the article's title expresses, it is the opinion of the author that developers shouldn't focus on writing documentation. Documentation is meant here as documentation for the user of the software not technical documentation I assume.

Well, I also assume that most developers love to code or construct and develop an architecture but don't like to write that much plain text for the stupid user (ironically, of course). This seems human. When working on a doctorate you notice that thinking about great ideas, getting inspirations, drawing graphics and schemata is refreshing and satisfying most time. But when it comes to clearly structuring the stuff, choosing correct, concise and consistent formulations (3 C's Law?) then the brain soon gets stuck, often.

For coding software the reason could be the break in paradigms between writing code and writing natural language. The latter implies a more or less informal system, a non-consistent grammar, ambiguous expressions and no compiler checking everything. The only thing you have at hand is perhaps the word processor aiding to some extend with simple grammar checks embodying the intelligence of a stupid child (which is astonishing as intelligent software is rare and hard to craft, IMO).

Test-Driven Development
There always is a problem letting an outsider (not a developer) write documentation. How does he know in which way the system works and what the intentions of the developers are? In my eyes, a documenter needs to understand at least a bit of software development. And if he knows too much, he would probably love to code and would not be the right person for documenting.

To get out of the mess a little, I like to suggest the idea of Test-Driven Development (TDD). TDD is not only a possibility of validating your code work as expected but also (or mainly!) a documentation tool. TDD expresses what your code should do. It's the same with Design Patterns, although many people don't recognize the documentation power of both Design Patterns and TDD!

So go write your tests and with that create a basis for other people understand your well-validated masterpiece in order to write documentation for it. Isn't that a valid approach?

No comments: