Documentation

I’m a procrastinator. Whilst reading The Procrastinator’s Handbook a few years ago (the only eBook I’ve paid money for IIRC) I discovered the main reason I procrastinate – I’m a perfectionist. Quite simply I put off jobs because I want to do a good job.

Sounds daft, but it isn’t. I don’t like half-hearted attempts or botched results (which make me an extremely bad DIY’er because I never start jobs, much to my wife’s lament), so I put off doing the job until I’m sure I can do it the best that I can.

This brings us onto the topic for this post – documentation. Loved by users, depised by documentors. I often struggle to write documentation because:

1. I don’t know what to write
2. I don’t know what to write it with

Once I get going I’m fine, but it’s that first step that trips me up repeatedly.

What to write?

Why are there not any guides out there that say “write these documents like this”? I’m talking everything here, from architecture documents to developer guides to user guides to release notes.

What to write it with?

This is a biggy. I want to be able to create all my documentation with as few tools as possible, and preferably support different formats/outputs.

I've tried various solutions - Microsoft Word/OOo Writer with PDF output, HTML, POD, Docbook, HTMLHELP, plain text. All work on one level or another, but there's no consistancy.

Docbook seems to be best of the bunch as it removes the emphasis on presentation that MS Word puts there, it allows multiple destination formats from a single source, and it plays nicely with SCM. It’s just so damn hard to use. Yet another syntax to learn (which is too close to HTML – it’s just asking for problems) and a problematic toolchain on non-UNIX platforms.

I want a documentation solution that provides something like the editing flexibility (and simple markup) of a Wiki, with the presentation control and output formats of Docbook. Anybody know of one?