I guess we could document it…


Case ConductorIn the process of developing Case Conductor, we have to make a lot of design decisions.  We are using Pivotal Tracker to manage our user stories, and that’s been working great.  Often, when we have chats about how to implement a story, we note the decisionright there in the story itself.  This is fine for us, but not very good for the future users of our product.

One day after having one such discussion, Carl Meyer, (our lead developer) decided that perhaps these design decisions would be best preserved in documentation.  What a concept!

There is a great little site out there for hosting documentation called Read The Docs.  Setup is incredibly simple.  Just follow the instructions here: readthedocs.org.  When you tell it your repo location (github, mercurial, subversion or bazaar), any time you check in new docs, they are automatically built to the site and you’re done.

So, over the weekend, Carl followed the above instructions to get setup for RTD.  Then he gathered a bunch of our design decisions, composed them in reStructuredText format and checked them into our repo on github.  Awesome.

You can find our current Case Conductor docs here: Case Conductor.  It’s not complete, but it’s a work in progress and it reflects the decisions we’ve been making on how things work in Case Conductor.  So, now as we have these discussions and make decisions, we immortalize them in the documentation.  It’s so easy to write them in this format, that it becomes just as easy to take notes right in the docs as it would in Evernote or a Tracker story.

Sphinx and reStructureText are used as the formats for the documentation.  This ends up being a very simple combination. Even reference links are easy to define.

For example:

Test Cases and Suites

.. _test-cases:

Test Cases

A **Test Case** is a named set of steps for testing a single feature or
characteristic of the system under test. Test cases are associated with a
:ref:`product <products>`, and can have one version per :ref:`product
version<product-versions>`. They can be organized via :ref:`suites
<test-suites>` and/or :ref:`tags<tags>`, and can have file
:ref:`attachments<attachments>`. Preconditions, assumptions, and other
preliminary information can be provided in the case’s *description*. A test
case can have any number of steps; each step has an *instruction* and an
*expected result*.


Doc example

While some editors support formatting reST documents, we have actually found it easiest to just build the docs and view them in Firefox.

make html

That’s all it takes, and you can view your docs locally in all their grandeur.

One of the other things I really like about this approach rather than a traditional Wiki is that your docs are with your code.  You don’t have to go to 2 different places and use an online text editor to update what you’ve done.  You can use TextMate, or Emacs, or whatever your editor of choice is, and check in the doc changes with the code changes.  Simple.