/ BLOG / Documentation! Documentation! Documentation!

I maintain a few how to guides and general documentation documents for a number of projects and communities, both open and proprietory, and I’ve come to a single conclusion; documentation sucks. The average user will not read, will not search and will not put one iota of effort into acheiving what they want, if they cannot work out how to do something within a reasonable amount of time. As cynical as it sounds, it’s true.

So what can be done about this sad fact? Honestly, I don’t know. Perhaps we should make things easier for users. Projects linked with the Gnome project, and itself, are trying this and at times risk annoying the “power users”, or advanced users, in doing so.

Unfortunately this isn’t always an option for some goals, such as running servers. In this specific subset of documentation perhaps things shouldn’t be made easy, to guard people against the dangers. My ex-gf’s step parent installed XAMPP for Windows (or equivilent) and then left it after getting bored. This was running on the main household PC, with an unprotected (anonymous access permitted) FTP server. I never did anything about it, for various reasons. I wouldn’t be surprised if it’s actually running as a pubstro right now. So why is this relevant? Because people don’t read warnings, in the same manner as they won’t do much research on getting software running correctly.

Granted often we all make misguided mistakes on the way to acheiving almost Zen-like knowledge in the field we choose. More often-than-not these mistakes could be, and should be avoided where possible, and that lies with the people providing advice and documentation. Is it really fair that the documentation writers make that decision for other people though? Ethically I believe we should all have the freedom to all make our own choices. Practically this doesn’t happen because the world and our knowledge is expanding we cannot possibly be informed enough to make all our own decisions. This is why the tertiary market exists.