Examples as documentation; documentation as specifications

Software with no documentation is like no software. If there is no description of how people can run your program, what kind of inputs and outputs it deals with and how you can interact with it most people will derive no benefit from your software. This goes both for “end user” programs as well as for libraries. Especially for libraries. An end user program at least you can fire up and start randomly poking at, especially if its a GUI program (And there are principles to follow to make such exploration more friendly). A library with no documentation? Forget it.

Documentation is as much, if not more, work as the actual coding. But it often feels like wasted work because the documentation isn’t actually making the software go. Also, sometimes people who love writing code, don’t like writing prose, or making diagrams, and so on.

In properly funded projects with enough priority given to documentation it is possible to keep the tutorials and references up to date by  normal management practices, mostly involving document writers working periodically with engineers before a release, going point-by-point through each page, cross-checking with the software and release notes and updating as needed, possibly done in concert with QA and testing.

In one person, open source projects, it is unlikely one has such luxury. What typically happens is that the manual gradually falls out of date as the software evolves and if you are lucky, and people are actually using your software, you will get puzzled and puzzling queries that lead you to update parts of the documentation, but you worry about the time taken away from core coding. And after updating the documentation, you realize that the example scripts are out of date, and so you might have to do those, and so on and so forth.

In order to deal with the issues of motivation and to control the extra effort of keeping all the pieces of documentation in sync with the actual functionality I’ve been experimenting with using examples as documentation, and documentation as specifications.

My current hobby program involves writing scripts to drive a simulation that can then be viewed in an interactive viewer. I started out in the traditional manner, by putting up a Readme with a “manual” section. Since I had input scripts, I created an examples directory with scripts. I realized early on that by putting comments in the example scripts I could make them self documenting and avoid having to repeat myself in the Readme – I just linked to the scripts. This was a short jump to doing what I always thought of as a neat idea the moment it was introduced to me: using the manual as the specifications document. So my readme and my scripts turned into a set of user requirements which gave me a decent idea of what I needed to code up.

(I was told that this was inspired by a practice as Amazon, where they would start out by writing the press release for a product, and then once the press release was done, they would turn that into user requirements, and then design and finally development)

So far this has been working fabulously for the kind of program I’m writing. I have, several times, changed the format of the scripts. I’ve only had to do this in one place – I’ve not had to worry about changing the scripts AND the documentation and I haven’t had to worry about keeping the specifications up to date – it’s all the same thing.

It turns out, also, to be a kind of test driven development. I call the script with my program, and the program complains about the parts of the script it doesn’t understand and I keep track of what I still have to implement and also have a set of test cases at hand to run the code on to make sure things are working as expected.

The downside to this, of course, is that the manual now refers to things that have not been implemented yet. But one must live dangerously.


One Reply to “Examples as documentation; documentation as specifications”

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.