Writing Reasonable Documentation

I find it strange that most people seem to be rather horrible at writing documentation. While this is simply a subjective opinion of mine (who am I to say that I am any better than they), it is one that many of my colleagues share.

Writing documentation, once you're in the mood for it, is quite easy. You simply explain how to understand/use a piece of software in a concise, mildly entertaining fashion.

Ideally, the software does a good job of explaining itself. If not, you may want to consider a new approach to your design (or accept the complications of your codebase's territory).

That's the best advice I can give to anyone trying to write better documentation (if they consider mine to be of any merit, that is).

Thoughts & Musings: a (Public) Journal

A collection of hand-written essays by Kenneth Reitz.