Software documentation is one of those things that is sorely missed when it isn’t there.  Why is it the last thing that any of us developers wants to do?  It seems that it is easy for us to ignore documenting in the heat of the situation, but we always get burned in one of many ways.

Literate Programming Style Code View

There are two situations that I get hammered with often.


Ever need to fix code written by someone who is long gone?  We need code comments especially when trying to understand code that someone else wrote.  Sometimes the code itself is not so easy to grok.  Its kind of like the textbook explanation that jumps over a bunch of important steps by saying “the rest is left to the reader.”  I guess that’s OK if the developer knows the requisite knowledge for the topic.  It is  unlikely that years from now when you are long gone that your code will be easily understood by the poor programmer who has to figure out what is wrong with it.

API Users

Ever try to use a library without an example to refer to?  When using an API we usually don’t have the time to do a deep dive into the code that we need to use.  We just need to understand the calling conventions and order of method invocation.  There are cases where we may  want to be able to do a deep dive into the source code.  Code comments are then important.  But the majority of us who are usinf APIs need documentation that is more geared towards tutorials, workflows, tips and tricks, and examples.  These artifacts if done well accomplish a number of objectives.

Users are More Likely to Give it a Try-
If you have good documentation upfront we will be more likely to dive in and try your project.  If not it  looks like your project is not quite ready for prime time.  I wouldn’t want to become dependent on it and most likely neither will developers.

Ease for New Developers-
For new projects on the open source side, we have a developer’s attention for a limited time only.  If they have to work a lot to unlock the value we have provided they’ll just go elsewhere and mutter something like — alpha.  If there is an easy to understand example that ideally comes close to what the user is trying to do then that’s a win-win.  For proprietary projects it is more a matter of getting proficient with the code more quickly.

API Inconsistencies-
Code evolves.  But when the API documentation does not evolve with it and downstream developers are dependent on it all sorts of bad things can happen.  Consider a case where distributed teams are working on separate components of a system. Usually the various components talk across APIs.  Each team may not have a view of the source code of the other modules.  If they do perhaps it is out of date.  Let’s say there are hundreds of changes over a week or two.  Demo day looms.  Testing uncovers a major problem.  Which module is it?  Finger pointing begins.  Perhaps  the definition of a field was changed in an API and the consumer wasn’t made aware of it.  These kinds of bugs can be pretty tricky to root out.  The situation could have probably been averted by using smarter tools that keep documentation in sync with code.

By investing the time and effort into generating quality documentation on both sides of an API, you can avoid a lot of problems and put out a higher quality product.

Here’s a link to an interesting paper that analyzes what information we developers typically need to be efficient.