‘open-source documentation is intrinsically rubbish’. discuss.

One of my flist, who has been wrestling with WP of late, found the following sentence on the wiki:

If you have ssh access, or can change the permissions through a command line interface, use the command “chmod 666 file.php” where file.php is the file that you wish to edit through the Template editing interface. If you can only access your files using FTP, the following resource might be of help: […]

Things that are wrong with this:

  1. Is there anyone out there with shell access who doesn't already know how to chmod a file? Really?
  2. It is confusing for people who don't have ssh access, don't know whether they have ssh access, and don't know what ssh access is. There is nothing to tell these people (i.e. the vast majority) that this needn't concern them.
  3. It implies that chmodding through FTP is the weird specialist option for people with limited resources, when it's kind of the other way around. Most users will have uploaded their files through FTP or the control panel, so it's easiest for them to use the same software for chmodding.
  4. It could very well send people running off to their hosts demanding shell access because they think they need it.

But complaining about the state of WordPress documentation is mostly pointless. I've come to the conclusion that to make a decent stab at documentation you need the following people:

  • A project leader who can define clearly what needs to be done, assign people to do it, welcome new volunteers and keep existing ones motivated
  • A talented technical writer willing to polish other people's efforts as well as writing their own
  • A team of willing minions

The chances of getting people with these skills to come on board and work without payment are vanishingly small, even if writing open-source documentation didn't happen to be a unusually thankless task (developers are bored by it and end-users take it for granted). People are often reluctant to take on the mantle of team leader if there's no pre-existing hierarchy; but if you rely on people to direct themselves efforts get duplicated, there's no quality control, the minions flounder around not knowing what they should be doing and eventually drift away. There isn't a lot to be done about this — short of hiring people in, which is very unlikely to happen — so if you're going to use open-source software you have to accept that the documentation is going to be rubbish.

(And yes, I was quite prepared to be a minion, but when the so-called head of the documentation team told me I should switch to Typepad because WordPress isn't aimed at non-tech people, I realised what a stupid idea that was.)

Leave a Reply

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

WordPress.com Logo

You are commenting using your WordPress.com 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 )

Google+ photo

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

Connecting to %s