Google Chrome cartoon rocks!

September 2, 2008

google-chrome-chris.jpgI haven’t seen the browser yet but Google Chrome’s cartoon is the best description of o piece of software that I’ve seen in a long time. Kudos to Scott McCloud – someone should convince our local cartoon star or my friend MiBé to do similar things!

Using graphics to explain stuff is obviously the best way, but the dynamics of the cartoon format (varying image sizes to emphasize importance, repetition of similar patterns and shapes to create a familiar universe in small steps) go much further than just combining images and descriptions. Not to mention the fun factor in reading it – everybody knows that people learn better when fun is involved.

I’m convinced – we need more of this to explain our often complex software systems.

Bertrand’s (tentative) Rules for Maintainable Documentation

February 19, 2008

On second thought, I’ll post my (tentative) recommendations for creating maintainable docs here, excerpted from my post to sling-dev.

These rules are meant for projects which operate limited resources. If your budget is unlimited, you might think otherwise ;-)

Rule 0: Less Documentation is Better

Create as little written documentation as required: every line of documentation that’s not automatically generated has to be maintained, and should be checked for each release.

If your system needs lots of documentation to be understandable, that might be a sign of a suboptimal or bloated design, or of a lack of good examples.

Rule 1: One Task, One Document

Avoid “big” docs that explain too many things.

The goal is to be able to say “this document is totally obsolete” when the time comes, rather than ” this doc has some obsolete stuff in it”.

Rule 2: No Duplicated Info

I’d rather point people to (readable) code to find out details about how certain things work, as opposed to duplicating the info in the docs and risking out-of-sync docs. The Truth Is In The Code – it just has to be expressed in an understandable way there, which also helps code quality.

Code tags (identifiable markers in code comments, which are referred to in the written docs) can help link high-level explanations to code that demonstrates the feature.

Dynamic things can be explained by pointing people to descriptive log messages that explain what’s going on. Why not create graphviz documents dynamically, like ActiveMQ’s connectionDotFilePlugin does, to explain dynamic things? The long-term impact of such efforts on the project is much higher than writing docs.

Rule 3: Examples are the Best Explanations

Apart from the overview and general principles, things are best explained by examples. The best examples are live ones, that people can play with immediately and that never go out of sync with the code because they *are* code. Or, as in the Lucene in Action book, readable automated tests, even if they don’t improve the test coverage but are here only as examples.

What do you think?