Posts Tagged ‘Software’

Twelve Lessons From Writing Documentation

November 18, 2007

We all believe good system documentation is important, but who actually does it?  The typical corporate IT system documentation usually consists of repository comments, a few moldering requirements documents abandoned on some network share and maybe a few inline code comments.

A couple years ago I finally tired of the standard “documentation process” and actually started to document some of what I do. 

Here are some lessons I’ve learned:

1) Like any skill, writing documentation improves with practice.  As skill improves it also becomes more fun.  (Yes, I said fun.  It really *can* be fun)

2) Some of the “classic” documents (requirements for example) turn out to have a very short useful life.  Other nameless documents—instructions for running a complex script—turn out to be highly useful.

3) Documentation is best written in short segments.  I use a wiki—it facilitates the kind of quick, “jot down an idea” thoughts that are often the most useful.  Writing in short segments also keeps it from getting boring.

4) Documentation must be easy to update.  Otherwise it gets out of date and looses the trust factor.  Again I really like the wiki for that.

5) Documentation must be easy to search.  Anything difficult to reference—like the traditional formal document stored on a shared drive—simply won’t be used.

6) Documentation is for programmers and users, not management.  Keep it professional (even if the document on multi-threading seems like it deserves that explicative!), but casual.

7) Keep documents small.  I prefer 1 to 2 printed pages.  If any single document is more than 3 pages long its coving too much ground and should be broken into its component parts.  It’s easier to navigate short documents and they are easier to search.  (Fewer false positives)  Leverage the power of the hyperlink!

8 ) Scale the documentation.  Systems are naturally hierarchical.  Systems break into sub-systems, which become classes and so on.  Let the documentation naturally break out into patterns that fit either the architecture, or usage of your systems.

9) Its OK to have documentation outside the code.  Documentation that’s tied to specific parts of the code should be in the code–class and method documentation for example.  But system and subsystem documentation may work better in a wiki.  The important thing is that the documentation is easily accessible and universally recognized as the place to go. 

10) Not all documentation is code related.  (For example, a dictionary of business terms/acronyms) There needs to be a place to store non-code documentation.

11) Documentation should answer questions of what, where and why.  The code already answers “how” so don’t waste time on that.  For those who think code is “self documenting”, just try to write code that explains why a particular design or architecture was chosen instead of a competing alternative. . .   Some of the most useful comments are ones like “we tried doing… but that turned out to be a bad idea because. . .”

12) Documentation should be shared.  The more eyes that see it, the more valuable it becomes.

But in the end, the biggest lesson–the person who uses my documentation the most:  me.  I’m amazed at how often I go back and read something I wrote to refresh my memory on a certain system, process or whatever.  The time I’ve spent writing has easily paid for itself just in time saved from re-researching.