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