I try to avoid writing static documentation. It gets old and out of date as soon as the next person comes along because it is logically far away from the code it describes, so event the best intended developers won’t always be aware of the documentation dependencies. Since working at Pivotal I’ve enjoyed writing tests first with RSpec, which results in one form of executable documentation to describe behavior to other developers working in the code base. But what about when you need to express behavior to people outside of your code base? Maybe your stakeholders have a company requirement of documentation, maybe you’re trying to entice third party developers to use your new HTTP API, or maybe you just want people to install your gem, what then? Your audience matters, and there’s a variety of tools out there to use depending on your needs.
Human Readable
Cucumber is one tool that can be used to fill this need. It’s designed to be a DSL for creating DSLs to describe your application. It has a nice attribute that it is very human readable. You can then use tools like Relish to publish docs from your Cucumber suite. The drawback is that you put a lot of effort in to expressing what you want in English, which is great if you’re really showing this to non-technical people, but it can be an over optimization if your readers have some technical context.
Dev Readable
In the case where your audience is an outside developer, something like rspec_api_documentation might be more appropriate. It layers on a DSL to your familiar RSpec DSL that lends itself to HTTP APIs. This is great because your RSpec tests become more expressive without the overhead of defining the DSL yourself. From there, you run a rake task to generate HTML. Your spec runs will fail if your docs get out of sync, which should be never if you have CI. The web is an easy venue to consume this kind of information, but the tool doesn’t let you editorialize much beyond the description of the resource and the parameters.
The Best of Both Worlds
One of our open source projects here at Pivotal Labs is Jasmine, a JavaScript testing framework that runs in the browser. Unlike Rspec where you need to have ruby installed and a database set up and so on, everyone has a browser. Check out the jasmine docs and scroll to the bottom. That’s right, the examples are tests, the comments are close to the tests so when the test fails you know to update the text as well, and now someone has a working example of how to use Jasmine all in one. The page itself is generated using Rocco, a Ruby port of Docco.With the combination of docs generated from tests, and tests that run in the browser you get this perfect blend of readable, easy to maintain documentation that is available to your entire audience.
Sometimes you have to provide documentation, but that doesn’t mean it has to be outdated. By creating executable documentation you can have confidence that the code and docs are staying in sync. Consider your audience carefully when choosing how you will document your software and know that there are more than a handful of options available, one of which will probably suit your task well.
About the Author
