philbull

I'm unhappy with the Ubuntu Manual project. I shared my concerns when it was first proposed:

This project is still worrying me, because I think you're making the
same mistakes that lots of people have made in the past.

• I worry that the project is not defined very well. It covers so many different topics, and I can't find any thorough definitions of who you are writing for. My guess, based on the level of writing, is that it's written for moderately advanced Windows users, people who know what the registry is etc. These people tend to be interested in computers already, so have additional knowledge. The average Windows user will NOT understand a lot of what has been written so far. [...]


• There is an immense amount of duplication with other documentation. The manual covers almost exactly the same topics as the system docs, circa two years ago. Click System -> Help and Support to see what I mean. If we ship the manual with the Ubuntu CD, then we'll have two different document sets discussing exactly the same things. This will confuse users.


• I worry that lots of contributors will lose interest after the first release, that you'll have a very large, complex project to maintain, and that you won't have enough people to do the work. Maintaining documentation is a thankless task.

(From a message I sent to the ubuntu-doc list on 13 Jan)

I don't think Benjamin, or any of the Manual guys, really listened to me back then. Since January, the manual has come on leaps and bounds - they've put a fantastic amount of effort into writing it, and they have something that looks very polished. So were my concerns valid?

Ill-defined, pitched at the wrong level

Thankfully, the level of the guide has come down significantly since the initial drafts I saw. I don't think that a guide to using the Terminal belongs in a beginners' guide, nor do I think that some of the topics will be of value to inexperienced users. However, there's not much jargon and discussion of irrelevant technical detail is kept at a reasonably low level.

There are some of the usual hallmarks of not having a good idea of your audience, though. There's a lot of listing, which is usually a sign that the writer thinks they should say something about a topic, but they haven't identified why their reader might be interested in the topic in the first place. An example comes from the "Media type" section of the "Connecting and using your printer" topic (p108). There's a list of the "media types" (types of paper, transparency and CD), but nothing that users are likely to find useful, like which way up to put the CD or what "Automatic" does. Focusing on tasks that the user needs to do, rather than tasks that the UI explicitly allows you to do, is much more useful.

There's also the usual mistake of reading the interface back to the user without explaining what each thing does, or without focusing on the most interesting settings (e.g. see p80, "If you don’t want to communicate with people on your local network, select the I don’t want to enable this feature for now option and click Apply." The implications of this are not explained - I doubt many beginners understand the chat autodiscovery feature in Empathy.) Another bugbear of mine is giving up because explaining is too hard, e.g. p105, "You can find your card manufacturer by referring to your computer manual or looking for the specifications of your particular model on the internet." Do you really think someone is even going to know where their computer manual is?

The Ubuntu Manual is pitched at a much more suitable level for newcomers than a lot of the Ubuntu guides out there, but I still think it's unsuitable for "average" Windows users. People tend not to realise how much they know about computers until they actually talk to a non-technical user; while it may look like it's written at quite a basic level to you and I, your average Windows user will probably find the Ubuntu Manual quite difficult. (Similar criticism could be leveled at the Ubuntu system docs, and I'm keen to work on fixing those issues.)

Duplication and maintenance burden

Look at the table of contents of the Ubuntu Manual and then look at the system docs (System -> Help and Support). Almost all of the material covered in the manual is already available in the system docs. In fact, parts of the manual are even taken and modified from the system docs! There is a very high level of duplication, as I worried there would be.

Rather than rewriting the system docs in a slightly different format, wouldn't it have been better to modify and improve the system docs and work on ways of getting them into a manual-type format? Linear manuals and topic-based help systems require two different ways of writing, but I see no reason why we couldn't find some solution which wouldn't have necessitated a 100% duplication of the content. Single-sourcing is commonly used in the commercial documentation world. All we need is the toolchain and a plan in order to do it ourselves.

Instead, we now have two large sets of documentation, the System docs and the Manual. They do not complement one another; they cover almost the same material, and the only real differences are mechanical (e.g. one is available as a PDF, one is HTML/built-in). The wheel has been reinvented. If we had worked together to improve the system docs, we could have done some really great things for our users. But instead, we're left with two things at roughly the same level, which suffer from roughly the same problems.

Because the manual is another internal Ubuntu community project, we also have an issue of user confusion. "Where do I look to get help with Ubuntu, the manual or the system docs? What's the difference? Why do I have to switch between the two because they cover slightly different things?" Some instructions in the manual will differ slightly from the ones in the system docs when discussing the same thing, so the user has a further headache when deciding which is more trustworthy. We haven't seen this yet because the manual hasn't been released, but I think we'll receive criticism for it soon. (I don't mean criticism from Ubuntu enthusiasts - most of these people think the manual is a good idea, but then they're in a position where they don't actually need to use the manual because they're not in the target audience!)

Another problem with duplication is the maintenance burden. I originally proposed that we work on improving the system docs (i.e. maintenance) rather than writing a manual from scratch, but we all know that maintaining someone else's writing is much less sexy (and more difficult) than writing it ourselves. So, if the manual is a product of unwillingness to tackle the difficult task of maintaining docs, as I believe it is, what will happen when it's time to revise the manual? I predict that it will be more difficult to get contributors to review and edit than to write, and the manual will start to suffer from the same problem as much of the other documentation in the FOSS world - neglect. We'll see if that prediction comes true in a couple of cycles, I guess.

What's worse, the system docs and the manual now have to compete for contributors, and the same pool of interested people has to handle double the amount of editing and double the amount of translation work to keep both projects alive.

Summary

In summary, I thought the Ubuntu Manual wasn't implemented in a sensible manner. We could have worked together and fixed a bunch of problems with the existing docs, but instead we've just doubled them in size, without really serving our users any better. So it goes.