The Documentation Gap

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.

Posted on November 6, 2006, in documentation, open source. Bookmark the permalink. 3 Comments.

  1. Hi Nick,

    The W3C doesn’t do a lot of documentation. Maybe it should. I wonder what is not ยซ documentation-by-comittee ยป because as soon you are more than one person editing a document, it is a committee. Microformats is a community with rules and process, WHATWG is community, IETF is a community, etc. Every groups have formalized (written or not written) process. It is part an internal building of any social groups being friends or industries.

    The hidden issue in your comment here is you are trying to hammer different communities with the same tools. Is it good to give a document which is a tutorial, a primer, a test suite and a specification in the same layout and the same wording. The big trouble is here. We receive plenty of comments from “end of the specification food chain” developers who find specifications far too abstract and at the same time developers asking for more technical stuff and less verbiage.

    See the problem. The problem is not that much the committee but the right document for the right target. A document is a way to help to define interoperability when you have more than one party implementing a technology, these parties not necessary knowing each other.

  2. Hi Karl,

    Yes, I know I was being a bit loose with my terminology. In the case of W3C, it’s some of your guidelines that suffer hugely from writing by committee. The WCAG – both 1 and 2 – springs to mind.

  3. Is it the writing which is suffering of the committee, or the issue which is difficult to handle in a address-it-all specification? WCAG is a very tough one, because it involves not only technology, but also social and human factors.

    It is always difficult to make the right balance. WCAG has been very useful to raise awareness about accessibility on the Web. Without it, I’m not really sure, we (people using the Web) would have made it an important criteria. That said, there is room for improvement, there is always, in any technologies we do. Should accessibility be addressed in a Web Content document trying to cover general principles of accessibility, should it be only in each technology case by case. Maybe a bit of both. Certainly one person or two friends writing an accessibility framework would address parts of the concerns, but would also forget others.

    For me, all of that is more like an ongoing process, where what we do is never finished and will never be. We all do mistakes, we also produce good things. The big interoperability problems these days on the Web is the lack of respect in discussions ๐Ÿ˜‰ Weblogs have been a wonderful way of letting people speak, but at the same time, not always in a constructive way.

    It’s always more benefitial for all of us to try to propose solutions and ideas, more than saying this is wrong. Though I admist it is harder to do.

    Many thanks Nick for this space.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: