More thoughts on Agile documentation

Matt Ryall responded to my post on documentation with some suggestions for making it easier. I finally persuaded my brain to give up some of the thoughts that it didn’t like (because they’d result in doing documentation). This isn’t particularly structured, just a few random ideas and concerns.

Stable code

What happens when part of the system is working perfectly, the customer is very happy with it and there are no changes likely in the future? No one is working on the code any more. No new developers are being introduced to the code base through pairing. Knowledge is slowly being lost from the system. Is there any way to identify code that’s reached this state? Are there any easy ways to produce a quick, high-level overview of the code?

If there are big sections of the code base which are stable, should they perhaps be separate sub-projects? Can a customer sign off sections of the project before the whole thing is finished? eg: an administration console, a look-and-feel or gui component palette, a logger, or a related standalone application?

Splitting a project up this way might help to reduce build times and complexity. The code would, however, have to be documented. For a library that may mean javadocs and clear code naming. For an application, that may mean a user manual.


Could a Wiki be scripted in some way so that out-of-date documentation is flagged? Do we need some kind of agile methodology for stopping Wikis from getting too big, too complex, and duplicating information? I can’t find anything I’m looking for on ours, because the bits and pieces which people put there three years ago are still there, and hardly any of it is relevant any more.

    Good things to put on Wikis include:

  • details of commonly used test data
  • TCP IP numbers of servers, etc.
  • Links to useful tech sites, eg: J2SE 1.4.2, JMock, Hibernate, etc.
  • VM parameters (we have about 20 of these and I don’t think they’re documented anywhere!)
  • HowTos
  • Reasons for choice, eg: “Why we switched to Hibernate”
  • A map showing the local pubs, bus stops etc.
    Bad things to put on Wikis include:

  • CRs, bug reports, etc. – there are better ways of tracking important bugs
  • Anything which people have to read regularly (use email updates; Wikis are passive)
  • Notes for new joiners (this should be emailed too, if only because people don’t like to email inaccuracies and out-of-date information, so it might actually stay relevant)
  • Anything which requires you to go through 3 other unrelated Wiki pages to find it
  • Lists of people on the project, half of whom left six months ago
  • Invitations to a special event in April 2003.

The flashing red light

My experience tells me that if there isn’t some big flashing light that goes off when something’s wrong, it won’t get fixed. For code, we have the red bar. What do we have for documentation? Matt mentioned using references to code names, etc., so that they are automatically updated.

Make documentation part of the build process, eg: if you’re using Javadocs and linking from one piece of code to another, run a script which checks for broken links as part of the build.

This entry was posted in Uncategorized. Bookmark the permalink.

2 Responses to More thoughts on Agile documentation

  1. anonymous says:

    I’ve thought about this problem at length as well, and I definitely like the idea a few short documents to describe certain architectural parts, the 30,000 foot documents that need to change very slowly.

    In addition we’ve been toying with the idea of assertion texts as documentation…

  2. sirenian says:

    The opposing thought I’ve heard is that if your test fails, you need to fix either test or code anyway, so you don’t really need text to document it (as all code should be self-documenting, shouldn’t it?)

    I’ve found it quite hard to write self-documenting test code in the past, mostly because it can be difficult to see the difference between initialisation, test functionality and verification. Maybe assert comments will help.

    On the other hand, one of my colleagues here pointed out that the best way to ensure that documentation is a) read and b) kept up to date, is to make it consistent. If the test already has sensible test names and comments to denote strange bits of initialisation, I think a coder is far less likely to read an assert statement, so you don’t actually get the documentation until it’s failed.

    Wouldn’t it be great if we could have a different sub-method of some kind for each stage of testing – the initialisation, the functionality, and the verification? Kind of like the “Given …. when …. then …..” of JBehave’s story-runner, but for unit tests too? I’ve seen this done using comments (one for each section), but it’s always the way that if you don’t force something, it won’t happen.

    Maybe each test should be a subclass, instead of a method…

Leave a Reply

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

You are commenting using your 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 )

Google+ photo

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

Connecting to %s