Channels ▼

Jim Dempsey

Dr. Dobb's Bloggers

The Lost Art of Writing Good Documentation

May 24, 2010

Recently I have been involved in, or more appropriately "struggling with", the conversion (port) of a Windows-based threading toolkit to Linux. This port is a work in progress and is now in Alpha test. The port should have been relatively straightforward to implement, and will likely be easy to implement the second time it is re-implemented.

What makes this port particularly difficult is not the functional design of the software, nor in the execution of the functional design into a well working set of source code designed for a specific platform. In this case the working software runs well on Windows x32 and x64. The difficult part is finding well-written documentation that distills most of what you need to know about an API into a single reference source.

This writer's programming background goes back to the late 1960s and I have witnessed most of the evolution of software development, the tools used, and the accompanying documentation. I have authored many software tools and the accompanying documentation.

As the evolution progressed in compilers (languages and dialects), run-time libraries and operating systems a class of tools was developed to aid in documenting computer software. Initially these tools did little more than pagination. Later, came the features of: titles, subtitles, formatting, different fonts, auto-generation of Table of Contents, and auto-gen of Indexes. Some of today's documentation tools go further to the point of if you comment and annotate your source code properly, that the document authoring tool can use these comments and annotations to produce a reasonably good rough draft, or more appropriately stated, outline for your documentation.

The problem, as observed by this writer, is the documentation writers do not "flesh out" the auto-generated document outline. The end result, from my perspective, is a compendium of function prototypes and an incomplete set of hyperlinks to related function prototypes. This lack of a comprehensive documentation is the cause for an inordinate number of hours in lost productivity.

As an example of this, I will choose a common general programming function from the C runtime library. My gripe is not particularly with this function, I do not need someone to explain this function to me. Rather the manner in which this function is currently documented is symptomatic of the subject of this article. The function chosen for this example is the file I/O open statement.

The following is from

The problem I have with the above documentation is, that above is not a comprehensive reference as to how to use this function.

For comparison purposes, let's look at what I would consider comprehensive documentation of the open function API. The source of this documentation is from the Borland C++ Version 3.0 Library Reference, Copyright 1991 by Borland International, pages 377-379.

What I find particularly useful in the Borland documentation, and sorely lacking in the documentation, is that Borland consolidates virtually everything you need to know about this function into this section of the document. This includes:

1. The/all #include file list as would appear in your application

2. function prototype

3. compatibility table

4. sample of the function call

5. list of and description of the required access flags

6. list of and description of the optional access flags

7. list of and description of the mode flags used when creating a file

8. a list of return values

9. a list of related library functions

10. a complete working example program using the function.

By contrast, the gnu documentation has:

1. mentions a required header, but not all required headers, and does not show an example #include as it would in your application (in the event the header is located off a different path)

2. function prototype

8. a list of return values

Missing are 3, 4, 5, 6, 7, 9, and 10.

These missing sections in the gnu reference require the reader to have multiple pages of the reference document open concurrently and mentally fused together to present the reader with the equivalent reference as presented in a nearly 20-year old reference manual.

Although this blog may seem that I am unfairly picking on contributors of their work in writing their documents, I wish to state my intentions are more towards gentle prodding to do better. Good documentation leads to better code writing and faster assimilation of knowledge.

Related Reading

More Insights

Currently we allow the following HTML tags in comments:

Single tags

These tags can be used alone and don't need an ending tag.

<br> Defines a single line break

<hr> Defines a horizontal line

Matching tags

These require an ending tag - e.g. <i>italic text</i>

<a> Defines an anchor

<b> Defines bold text

<big> Defines big text

<blockquote> Defines a long quotation

<caption> Defines a table caption

<cite> Defines a citation

<code> Defines computer code text

<em> Defines emphasized text

<fieldset> Defines a border around elements in a form

<h1> This is heading 1

<h2> This is heading 2

<h3> This is heading 3

<h4> This is heading 4

<h5> This is heading 5

<h6> This is heading 6

<i> Defines italic text

<p> Defines a paragraph

<pre> Defines preformatted text

<q> Defines a short quotation

<samp> Defines sample computer code text

<small> Defines small text

<span> Defines a section in a document

<s> Defines strikethrough text

<strike> Defines strikethrough text

<strong> Defines strong text

<sub> Defines subscripted text

<sup> Defines superscripted text

<u> Defines underlined text

Dr. Dobb's encourages readers to engage in spirited, healthy debate, including taking us to task. However, Dr. Dobb's moderates all comments posted to our site, and reserves the right to modify or remove any content that it determines to be derogatory, offensive, inflammatory, vulgar, irrelevant/off-topic, racist or obvious marketing or spam. Dr. Dobb's further reserves the right to disable the profile of any commenter participating in said activities.

Disqus Tips To upload an avatar photo, first complete your Disqus profile. | View the list of supported HTML tags you can use to style comments. | Please read our commenting policy.