Documentation: the missing tyre

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.