niq’s soapbox

Quim Gil makes some pertinent observations on the documentation gap. He’s attracted quite a few comments, including one from me. Since commenting there, I’ve thunk further thoughts on the issue.

Firstly his points: there’s a shortage of people documenting gnome, and (he supposes) free software in general. But there’s no shortage of translators, nor of techies writing - the latter in the context of blogs. My response: documentation is a much more demanding task than translation or blogging.

But there’s still more to it. When you document a project, you study it in detail, you see what’s wrong. If you have the hacker mentality, you want to go and fix it before documenting something that’s not right. That applies mostly at the top end of documentation, where accuracy and thoroughness are expected.

Another observation: Commercial software shows a different face of the same problem. Documentation exists, because someone is forced (and paid) to write it. The first iteration isn’t (necessarily) so bad, but then some pointy-haired middle-manager insists on a bunch of changes that distort it out of all recognition. The end-result: documentation written to process, that is utterly useless and bears little resemblance to reality. I struggled last year with Oracle’s truly appalling documentation, and my blood pressure rises every time I have to try and use Microsoft’s.

I won’t get started on documentation-by-committee, that affects organisations such as the W3C. Not today, anyway.