The Goldfish Chronicles

Having watched Maven for a while, I thought I’d use them as an example for this piece.

Early on, Maven had great docs. They were up to date with CVS [as no release had been made] and lured users in to using Maven. When the first release happened, the docs continued to move forward, staying synced with CVS. This meant that features documented were not available to the average user, but there was no indication of this. This continued for a short while until the documentor got into other things and the documentation started to stagnate. New releases happened, and soon the documentation did not represent the source code that had been released.

Nowadays things are better. Documentation is in or around the area of the release. The addition of a wiki has allowed a lot of dynamic information to enter.

So… what’s the point of that story? It’s not to try and moan at Maven. I think their docs have over the last 2 years been very good. The point is that documentation releasing/management is very hard.

[rambled long enough, moving to the extra section for more…]So. How do we handle releasing of documentation?

In the slow slow world of closed communities, the documentation releases with the code. It’s called a product. The code is held up while the documentation is deliberated over and any lessons learnt post-release are never documented and released. When did you last receive a bugfix for your help-pages or your manual? Errata releases do seem to happen, but not with any real cohesion.

In the fast fast world of open communities, the documentation release is not allowed to hold up the code release. This is good. Open communities tend to rely on online publishing [in fact this is a lot of what makes them open] so this allows them to push out bugfix releases to documentation very aggressively.

There is a deep problem however in the versioning. While we version our code releases, and include some downloadable documentation with them, we don’t version our websites. Sometimes, as Maven now does, we mention that this website is for code release version X and was last updated on date D. I’ve even taken to linking to the old sites for a particular version. Is this enough?

Lastly…Javadoc. It’s bad because it is tied to the code. We all like to ooh and aah over literate programming [it’s sweet], and javadoc is a bastardised hack of literate programming. But both tie the documentation to the code. Now, for the API contract, this is good. The code and the contract are the same. But when the documentation starts to become a manual, it could be bad if the website has any information in it.

It seems there are two choices for an open source project to take. In Java terms these are:

1) Release code with the API contract alongside but nothing else. Then you maintain a documentation site for every release of the code. [deprecating as reason permits]. This is ‘untying the code/docs’.

2) Put all the documentation in the release, ie) the Javadoc. The only way to update the documentation is to release a new version. This is ‘tying the code/docs’. The website is then an utterly different product to the code, it is a marketing/delivery mechanism and does not provide any real information.

In reality I think we all try to do both, and end up with a confusion for a user. When they download product X, they get some kind of documentation with it. It’s relevant to the download, but without errata fixes.
When they look at the website for product X, they see another set of documentation, which is up to date and includes things like articles etc, but is not relevant to the download.