Channels ▼

Al Williams

Dr. Dobb's Bloggers

The Sad State of Documentation

October 28, 2010

I haven't always been a writer (and some would argue I'm still not since I'm still not working on the great American novel). I came to appreciate the power of language later in life. So I can sympathize with the dread many developers feel when they have to write documentation.

However, I've noticed lately that as a community our writing and documentation skills are noticeably dropping. Not a week goes by I have a meeting with developers who can't clearly explain what they are trying to do or why it is failing. Many well-written pieces of software have dismal documentation. Even finding poorly written articles in magazines and journals (present company excepted, of course) seems to be a more common occurrence.

Case in point: I was reading a magazine last month -- I won't mention the name -- and there was an article about converting binary numbers to BCD. The author mentioned the technique converted hexadecimal numbers to BCD which isn't really accurate, but I could forgive that.

That was the least of the problems, though. After reading the prose, I had no idea how the technique illustrated worked. Total confusion. Just to amuse myself, I tried writing code in C based on the description to see if it would work. Of course, it didn't. Finally I opened the assembly code provided with the article and studied it. I was able to generate the C code to match. It worked but there were several unnecessary extra steps included in the original code that I was able to remove. Overall, very sloppy.

And its not just articles. I've recently been working with a vendor's "standard library" for a product. Its actually quite good, but the only documentation is automatically generated from comments in the code. That'd be great if the code were significantly commented. I've seen people use Javadoc or Doxygen to build great documentation. But just dumping out whatever comments you happen to have into a file doesn't substitute for documentation. Those tools are just that -- tools. They don't build documentation any more than a hammer builds a house. You can build a great house using a hammer, but the hammer really isn't the important part.

So why is this? Is it a failure of the education system to teach communications and critical thinking? Is it our short attention span that can't get through a single tweet? Is it because shrinking budgets don't allow for documentation? Or am I just turning into a curmudgeon? I guess that's possible, but I don't think so.

Granted, there are some great examples of documentation out there. PHP comes to mind. But even projects with great documentation sometime fall short in areas (try porting gcc to a new target).

I try to subscribe to the golden rule. We are all programmers. We've all picked up code to maintain or a library to reuse that had great documentation. And we've all inherited code with lousy documentation. So we obviously can tell the difference. I figure if I write documentation that I would be happy to read I've done my job.

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.