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.
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.
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
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.