by Alex Rozanski

Documentation: the missing tyre

Sep 23rd 2009Published in Software

Technical documentation is everywhere, and pretty integral to software development. But a lot of documentation is:

  1. Poorly explained
  2. Missing significant parts
  3. Lacking depth

(or a combination)

After all, documentation is the “missing tyre” of project management:

But let’s face it, writing documentation is hard. Software projects, especially large ones, are constantly changing, with bits being added, removed or changed, and sometimes anticipating how your audience of developers will use a particular framework or API can be something of a challenge. And writing well in a manner that effectively communicates what you want, in the way that you want is something of an art (you can see the irony here).

Of course, there are many tools which help to make documentation easier, such as javadoc, Doxygen or phpdoc, amongst others, and they can make documentation easier by linking the coding and documentation process, which brings a certain consistency between the two, but there has to also be consideration of what your developers need to know, and not just blind regurgitation of what’s in the source.

From a developer’s standpoint, I like to judge documentation on what’s not included, as opposed to what is. Because there’s nothing more frustrating than trying to use someone else’s code and being in the dark on how you do so.

Catering to everybody’s needs is hard; and there are two categories of those who use documentation, which are not necessarily distinct:

  1. Those who use the framework or API. People in these situations want to know how to use the code, and in a quick, but sufficiently detailed manner which enables them to do what they want with the framework/API. They don’t necessarily care about the internals unless it affects how they use the library.
  2. Those who want to extend the code, or have an interest in the internals. People who want to extend the existing functionality of the framework or API for their own means fit into this category, and they often need to know some of the internals and design – to some degree – of the various components. Therefore, documentation catering to these users will need to be more detailed and go into more depth.

But what – in a general sense – makes good technical documentation? There are several points that this covers:

  1. Provide complimentary articles to provide extra information about the code being documented. It’s good to have classes, methods or functions documented, but when it comes to taking a step back and using the code together as opposed to as separate chunks, with little or no prior knowledge, without these it becomes something of a challenge. I feel that this is executed well in the Apple reference library for their frameworks. For all of the classes that are documented, there is a section titled “Companion guide(s)” which lists other documents (if any exist) that relate to that class, which provide further explanation. For example, with the NSButton class (which is a class used for button UI elements), there is a “Button Programming Topics for Cocoa” guide, which explains the topic twofold:
    • Background/introductory information on the class
    • How to use the class

    I think that the second part is crucial to good documentation, because it brings together all the separate methods and being documented and explains how to use them together, and both documents provide a starting point for those who have little or no idea how the class operates.

  2. Explain the crucial details with enough detail but not to extortionate lengths. With method calls these are typically:
    • The method signature
    • The parameters expected (if any) with expected types
    • The return value

    Although of course methods are not the only things being documented – there may be types, constants or defines among other things; and this is one of the parts at the core of the documentation, so doing this right provides quick and easy entry for those who are looking up how to use a particular method, function or symbol.

  3. Explain other important points. Typically placed in a “remarks” section or similar, this section should explain any unusual behaviour or important information for the developer that they may need to know when using the class. This is important because it stops developers from being in the dark about how deeper parts of the class operate, and things that may generate errors, for example, or should be noted.Another point of particular importance is the minimum requirements or limitations for using the method, if such limitations exist.
  4. Provide hooks to other related parts of the documentation. This is an important feature for making the documentation quick and easy to navigate. For example, if there is documentation on the C/C++ malloc() function (used to allocate memory), it would be useful to also provide a link to the section documenting free() (used to free memory). This caters to developers who want to navigate the documentation quickly and easily.
  5. Clearly mark deprecated methods or functions. This is important to help move developers away from legacy code if it is appropriate, but without completely removing it from the documentation to show that it did exist, and it may be required in some instances.

But the most important point is to keep the developers in mind. Anticipate how they will be using your code, and what they need to know, and what they don’t need to know.

Good documentation is a compromise between providing developers with the relevant information in sufficient detail in a consistent manner whilst not being verbose.

Comments — 6

  1. Ólafur Waage

    Sep 24, 2009

    The second point gets me the most. I have the documentation of some item, it says that I can use it in some way but it doesn’t show how.

    So examples or a place for examples is an awesome addition to any documentation. People should look at jQuery’s documentation for great examples of examples 😛

  2. perspx

    Sep 24, 2009

    > People should look at jQuery’s documentation for great examples of examples

    Yes the jQuery documentation is great because there are so many pieces of example code, and there is also an overview section to each API function which explains a bit about the function as well.

  3. Diago

    Sep 25, 2009

    Well said. I have that exact image up in my cubicle at work, along with the image of how Apple and Google design software. I am in charge of training a group of about 40+ hardcore developers in .Net, and I find examples of the above every day at some point. It’s amazing that we have 200+ Delphi applications running our business because of this.

    Thankfully being rewritten now, with that image reminding me everyday of what NOT to do.

  4. perspx

    Sep 25, 2009

    Ah, great cartoon!

    And yes, I don’t think in most cases it’s intentional, but developers forget that other developers don’t know how their code works, especially so if it’s something that they have been working on for a while and know inside out.

  5. rx512

    Sep 26, 2009

    Funny thought, even if your documentation is amazing, since 99% of docs out there well.. isn’t, people aren’t likely to look at it.

    Take my mum.
    She wasn’t sure how to superscript in OpenOffice when she was typing something up on my OpenSUSE laptop a few hours ago.
    She just left it as is, and when I asked her why she didn’t look at the docs, she said that she knew she wouldn’t find anything useful in there xD
    And she’s like, technologically illiterate.

  6. perspx

    Sep 26, 2009

    Yes I agree – I see loads of people who don’t look at documentation for things at all because they know they won’t find anything useful, which I guess is fine for certain products because you can – in a lot of cases – stumble around and find what you want anyway.

    However I was talking more specifically about technical documentation which you DO need to read in order to know how to use some API or framework (you can’t exactly stumble around a framework and expect your application to be robust) – yet a lot of it is poorly documented which makes the whole process a hell of a lot more painful.

Add comment

Please enter your name and comment