Automate Your Documentation

Editorial Note: I originally wrote this post for the SmartBear blog.

Few things, I’d say, strike boredom into the developer heart faster than the subject of documentation.  Does anyone out there really just love wrapping up development on a feature and then cranking out a Word document with a bunch of screen shots and step by step instructions.  Or, perhaps you fancy the excitement of pasting a legal header above a class you’ve just written, and then laboriously documenting all of methods, variables, and function parameters in the class?  If not that, how about the thrill of going back and updating comments that no longer make sense after the code has changed?

I suspect I don’t have a lot of takers at this point.

Documentation is boring, at least for the overwhelming majority of us.  After you’ve built a thing, you want to go build another thing — not rehash in laborious detail what you just did.  And yet, documentation is essential for communicating across time and teams to other people.  Your users will need documentation.  Future maintenance programmers need documentation.  Unless you’re going to be around in perpetuity to handle all that comes, you need to leave some sort of persistent knowledge transfer vehicle.

But that doesn’t mean it has to be tedious, repetitive, or boring.

Repetitive labor offers a certain counter-intuitive appeal, since it creates a “pain is gain” feeling of diligence and accomplishment when complete  But don’t be fooled.  People make many sloppy mistakes when doing repetitive tasks and drudgery is a terrible use of company money when you’re collecting a salary as a knowledge worker.  As people in the software industry, we earn a living automating grunt work out of existence, so let’s take a look at how we can help ourselves when it comes to documentation.

Use a Collaboration Tool

First up, let’s consider something that may seem not quite to fall under the heading of automation.  I’m talking about using a collaboration tool such as a wiki or Sharepoint.

If you do this, as compared to, say, having a bunch of Word documents on a shared drive somewhere, you realize some immediate benefits.  Utility like search and creation is already defined, and there is a pre-set flow to how things are put there, managed, and maintained.  In this sense, you are automating your work by letting the tool do it for you.  If you’re not already taking advantage of something like this, I highly recommend doing it as a “mini-automation” first step.

Generate Architectural and Design Diagrams

Next up is something that falls under the heading of what you would more traditionally think of as automation.  Are you in the habit of creating diagrams to document your architecture or design?  These might include sequence diagrams, class diagrams, flow diagrams, etc.

If you are doing these things, then when you’re doing them matters.  If you’re doing them speculatively, ahead of actual implementation, I wouldn’t make a whole lot of effort to capture them in the first place, since they’ll probably become quickly obsolete.  Design up front on a white board and be ready to adapt as you go.

If you’re capturing your architecture and design after implementation, for the sake of knowledge transfer and reference, then using a tool like Visio to draw them by hand wastes your time.  There are plenty of IDE plugins and standalone tools that will analyze your codebase and generate diagrams like these for you.  Seriously, there’s a rich set of tools like this out there.  Before you ever draw anything by hand, make sure you exhaust your options for having the drawing done for you.

Templates for the Boilerplate

Earlier, I mentioned the concept of a legal disclaimer that goes at the top of every file.  At a lot of large companies, this will contain copyright information or the like.  This type of activity is documentation boilerplate in the truest sense of the word.

If you find yourself copying and pasting something like this (or worse yet, typing it by hand) every time you create a new file in your codebase, you’re throwing away your time.  Most IDEs and editors will have functionality that lets you insert text — even templated text — with a keyboard shortcut.  Alternatively, you can even automate in such a way that there mere creation of a file with a certain extension pre-populates it with documentation text.  Or, if you want to get really sophisticated, there are templated text transforms, such as Microsoft’s T4 text generation tools.

Whatever you use, make sure you’re not spending time putting the same text into files over and over.

Generate Method Comments and Help Documentation from Source

Automation isn’t just for big chunks of static boilerplate text.  You can also automate your method and class comments as well.  And I’m not just talking about a handful of commented out lines ready for you to type — I mean functionality that takes your method or class, and generates comments about the arguments, name, return type, and even, to an extent, what the method does.

This might sound like black magic, but these tools really exist and do a good job.  This is doubly true when you use them as a starting point.  Generate the comments and then take a look to make sure they’re good, tweaking them as necessary.  This is much better than typing it all yourself, and much easier to do without getting bored and risking typing vacuous, nonsensical, or wrong text.

And this can work for more than just comments in your code, too.  You can actually use tools like this to generate online documentation and help files that look quite professional and are consumable by end users.

Example Generators

The final option that I’ll mention is tools that generate not only documentation that you might need, but examples to boot.  If you’re an API author, this is a powerful concept.

As a developer, do you like to pour through many pages of documentation, reading about an API?  Or would you prefer to start with a quick intro and a series of examples that you can use, get going with, and tweak?  I can’t speak for everyone, but I strongly prefer the latter and I suspect many reading would as well.

Like any other form of documentation, there are tools out there that can take your API as input and help you generate actual, example code.  You could do it yourself, buy why bother when there’s a tool that can do it for you?  Save your energy for reviewing the results and moving onto your next feature when you’re satisfied.

Sky’s the Limit

The great thing about writing software for a living is that your ability to automate is limited only by your imagination.  I’ve outlined a series of different kinds of tools that can help you get your documentation done more quickly and with far less boredom.  But you could, no doubt, dream up plenty more on your own, and even implement some of them for your group.  The sky is really the limit here.  Just remember that when something is necessary but mind-numbing, there is probably a tool out there to make it easier.  And if there isn’t yet, there’s nothing stopping you from making it.