Documentation – What’s The Secret Sauce of Enough But Not Too Much?

Documentation.  Although every developer needs it, most dislike the thought of creating documentation while complaining vocally when it’s lacking.  Creating proper documentation is also expensive, requiring hours of developer or specialized staff time, and even more time is needed to keep documentation current as projects evolve.

But failure to keep code documentation current can be even more expensive.  At best, out-of-date documents can be confusing; at worst the misinformation can cause expensive bugs or lengthy refactoring efforts.

I’ve seen documentation done right only once, at a defense company, and that was largely because the government demanded a rigid process.  But under this model, doing it right meant a full-time staff of technical writers – an expense most start-ups or small businesses cannot afford.

My first programming experience was at the government contractor mentioned above.  I was young and anxious to code up a storm.  Much to my chagrin, I discovered a documentation-to-code ratio of about 3:1.  For every month spent coding, at least three months were spent in meetings and creating documents.  I learned to hate documentation.

I left that job in the early 90’s for the golden pastures of my first Internet start-up.  In my first week I asked for some API documentation.  I was answered with laughter, perhaps even subtle derision.  There was no documentation.  None.  Nada.  Zip.  It was all about code.  Lots and lots of fast code.  Plus, who needed documentation when you could just look at the volumes of code?  I spent many late nights reading thousands of lines of uncommented and poorly formatted code.  All of a sudden comprehensive documentation sounded really nice.

When I later moved into leadership roles, I tried to find a balance between documentation costs and being complete.  Admittedly, it’s been difficult.  I still like the idea of being comprehensive and feel personal failure if I can’t quickly produce accurate API documentation.  This is particularly true when collaborating with outside groups. However, finding the “right” balance in the start-up / small-business environment has been near impossible.  After much experimentation, I feel like I’ve found a solid mid-ground.

The following ideas work well for me. Your mileage may vary dependent on your product, team, or environment.

1. NEVER create stand-alone documentation.
   It nearly always goes out of date within months/weeks/days of being produced and you will never find the time to update it. I find this to be increasingly true with the advent of shorter development cycles and agile development methodologies.
2. Documentation should ALWAYS be an artifact of coding.
   It should be a seamless extension of the coding process, meaning documentation is added directly to the code at the same time the code is created. I’m not talking about simple code comments: I’m referring to document snippets that can be yanked out of the code and compiled into neatly formatted documents. There are many tools that will do this. I run an open source shop where JavaDoc and RDoc are best friends.  Many of our products export web services.  Documenting the resulting API is hugely important and a significant time saver for the consuming party.  We use Web Services Description Language (WSDL) documentation tags and the wsdl viewer style sheet.  The following example illustrates:

   <?xml version="1.0" encoding="UTF-8"?>
   <?xml-stylesheet type="text/xsl" href="wsdl-viewer.xsl"?>
   <wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/">
   
   <wsdl:documentation>Web service overview
             Copyright (C) 2011
             ACME, CO. All Rights Reserved.
   </wsdl:documentation>
   
   <wsdl:portType name="ACME">
         <wsdl:operation name="createUser">
              <wsdl:documentation>Describe this service here. </wsdl:documentation>
         </wsdl:operation>
   </wsdl:portType>
   </wsdl:definitions>
   

3. Documentation MUST be created at the same time the code is written.
   Spending two or three minutes to document a method signature as the method is coded is palatable. Spending several days at the end of a project to document the entire source tree as a final step is not.
4. Automated documentation generators MUST be run (without errors) at least once before every release.
   I’ve lost count of the number of times a JavaDoc error has lead to the discovery of a very subtle logic defect. Typically this can happen when the JavaDoc is updated in anticipation of a parameter name change, but the actual parameter is never modified. The code compiler won’t care because the data type didn’t change, but the JavaDoc compiler complains from a mismatch between the documentation tag name and actual parameter name.
5. Documentation MUST be a priority.
   Telling your staff to document is not enough. As a leader, you must do it yourself. Don’t go through the motions either. Do it well and lead by example. Public display and acknowledgment of particularly good documentation from team members works well too. Don’t forget to pad time estimates slightly.
6. DON’T forget the index page.
   Most documentation generators allow for an index page where the project as a whole can be described. I put this idea last because I’m struggling with it. On the one hand, I find that a good JavaDoc/Rdoc overview helps tremendously with orientation while increasing the speed at which a new user can learn, use, and understand a new API. On the other hand, the overview is not really an artifact of coding. A developer needs to go out of his or her way to create a special stand-alone document. As a result, the information can go out of date quickly and needs to be maintained. Ultimately, this violates idea number one. In the very least the stand-alone documentation has been isolated to a single, accessible spot.