Documenting Side Projects

No documentation or self-documenting code are as bad as documentation for documentation’s sake. So what to use on a project which will be developed in bursts from time to time?

While working on SlothCMS my first approach became to create a high level documentation where I wrote about Toe language syntax and where to put what with regards to configuration. This approach is not a bad one. Unfortunately it’s not enough to track progress, the most important thing when working on project solo.

Personally I need to have milestones when I work on something1, so Spiral and Waterfall are two paradigms which are worth following. Spiral works for me because it’s cyclical and I have maneuvering space when there’s a change in plan. My documentation practices reflect this.

Mid-level/Stages

My stages are stored in XML format in their own directory in order to separate from high and low level documentation. Stage files follow this format:

In the main features section are described features in general terms and serves as a summary of the most important things to be in the stage.

On other the hand in goals section contains brief description of cards created from the main features. In attributes there’s a reference to the card name and whether the card is done.

There’s also a table section which I currently don’t use while working on SlothCMS because there’s no SQL database. So this section might get reworked in the future and possibly add NoSQL section.

Low level/Cards

My cards are in XML format and in separate directory as well. One thing which was necessary because the number of cards can get big very quickly is to separate cards by stages. Example: <Project Root>\docs\cards\stage-X\card-Y.xml

The card format is:

At first I had there only name, status and description because I thought that it would be enough since it’s a fairly simple project which would need something more complex. I was wrong, now I am convinced that beyond “Hello World” there’s no such thing as “simple project”.

Addition of acceptance criteria section was necessary because description can be as long and descriptive as one is willing to write but my needs required thing similar to a check list.

Next added section, dependencies, is for making clear that something has to be implemented first. At this point there are no plans to add a tag depended-by as there’s no need for it at the moment.

Code level/*Doc, comments

“Self-documented code is documented for the next six months.” — Mickey Ariel

“If you are lucky.” — Me

I heard Mickey to say that at PostgreSQL meetup in Prague where she gave talk Docs or it didn’t happen. Unfortunately not all developers2 consider writing comments necessary.

As a human I do consider *Doc to be somewhat writing documentation for documentation’s sake but *Doc is not primarily for humans. It’s for bots3 to create an index of terms that appear in my code. Code index is the same as index in non-fiction books, when you need it you are really happy when you find one.

Writing comments outside of *Docs is important only when I am writing something that’s not described enough in a card and brevity is important for quick orientation in the code. Writing novellas in comments is very bad use people’s time.

 

  1. I am not thrilled when it comes to working agile way
  2. coders, programmers, ninj-code clowns
  3. Pieces of code