Twelve Lessons From Writing Documentation

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.


Tags: ,

5 Responses to “Twelve Lessons From Writing Documentation”

  1. Mike Coon Says:

    One comment about using hyperlinks. I like to create documents in an outline form and put the detail in a linked doc. That way I can write something like ‘Create Build List’ as one of many steps with a link that a new user can go to for the detailed instructions on how to do it.


  2. Soon Hui Says:

    Nice post, Jeff.

    I did try to document my code, using various tools, including plain Microsoft Word, Microsoft Visio and XML in-code comments. I must admit that none of these worked very well. Even the XML in-code comments had very little usefullness because more often than not, I didn’t bother to update any documentation when my code underwent changes. And you know, dead comments are useless at best and misleading at worst.

    So now instead of trying to explain what the code is doing or why it is there, I tend to rely on short methods to self document. After all, the documentation that really counts, is the code itself.

    However, there is one place where I document my code religiously– The related bug numbers in a bug tracking repository of a test case. It is really useful because it allows me to understand what the test case is doing and why it is there.

  3. Stephane Grenier Says:

    Hi Jeff,

    Great post! And I can’t agree enough with you that a wiki is great documentation tool. It’s much better than a shared directory of documents. Not only that, it really facilitates a lot of the good suggestions you give (such as breaking it down, etc.).


  4. James Lloyd Says:

    My motivation for documentation is two fold:

    1. Remind myself when I forget how I did something.
    2. Gives me a convenient place to point people when I don’t want to do something: “everything you need to know is on the wiki”.

  5. [Traduction] La documentation vous apprend 12 choses « Opensource et Web2.0 Says:

    […] Publié le mai 12, 2008 par Sarah Haïm-Lubczanski Ce qui suit est une traduction libre du billet Twelve Lessons From Writing Documentation de Jeff Staddon, paru en novembre […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: