ubuntu-manual team mailing list archive

[Benjamin Humphrey <humphreybc@xxxxxxxxx>]

Here are some comments from one of the Ubuntu Documentation team
members, that I thought everyone should read. He has some valid
points.

------------

Hi Benjamin,

Thanks for answering those questions. I've provided some thoughts/advice
based on my experience, below. I hope you find them useful.

TARGET AUDIENCE

It's extremely important to have a very good idea of who your target
audience are. The problem with writing documentation is that it's very
easy to write something that you understand, but it's not so easy to
write something that other people will understand. Try (verbally)
explaining a concept like "hardware drivers" to someone who is not
technically inclined, and you'll see what I mean.

You need to figure out who your readers are, what they know, and what
they are trying to achieve (i.e. why they are reading your document).
That way, you can make sure that you are adequately catering for their
needs. The most common way of doing this is to develop a few personas
[1] which represent your users. The doc team can offer lots of help with
this, if you like.

In the FAQ, you say that the level of technical ability ranges from
newbie to someone who is familiar with Windows. Be very careful with
this; we've found in the past that writing for experienced and
inexperienced people at the same time can lead to docs which aren't
useful to either group. Inexperienced users need lots of things to be
explained and jargon to be avoided. Experienced users don't care about
most of this, and are just looking for specific information, such as a
command. The experienced user will then find that the information which
is interesting to them is buried in a load of irrelevant stuff, which
makes the document difficult for them to read. This was what my question
6 was about; you can't satisfy everyone.

MAINTENANCE

Writing a document is lots of fun, and it's typically not too difficult
to get people involved. However, once the document is written and you
need to maintain it, the task becomes much more boring. This is
something that the Doc Team struggles with; only a few people are
interested in keeping documents up-to-date. Maintenance involves
reading, checking and modifying the whole document, every six months in
our case. This can be very tedious, especially if major changes have
been made over that release cycle. Maintenance is more difficult than
writing because writing allows you to exercise some creativity; when
performing maintenance editing, you are constrained by the material that
is already written.

It's also good to think about what happens if *you* lose interest in the
guide. Who will maintain it then?

TRANSLATIONS

I saw that you'd chosen to write the document in LaTeX. I'm not sure
what translation infrastructure exists for LaTeX, or whether it's
compatible with Launchpad's Rosetta system. You should also be aware
that translators need lots of time to work on a document, especially if
it's 50 pages, and that screenshots can be difficult for translators to
handle.

LICENSING

Please don't use the GPL! It makes remixing and reuse pretty much
impossible, and I think it requires you to track versions in an awkward
way. CC-BY-SA is the license the Doc Team recommends.

CHOOSING TOPICS

I see that you're choosing topics based on forum threads and existing
community docs. This will seriously bias your choice of topics, since
you'll only be picking up suggestions from people who are interested
enough in Ubuntu to be reading the forums on a regular basis. These
people are likely to have a higher level of technical skill than
average, so you'll get suggestions which are too technical for most
people, and you'll miss lots of issues which novices really struggle
with. You'll probably end up with a section on configuring compiz or
fluxbox, and miss out the section on "Where are my programs?" if you
just use suggestions from the forums!

A good way of choosing topics is to find people who match your user
personas and then watch them trying to use Ubuntu (without prompting
them or telling them what to do when they get stuck). This can be very
revealing - you'd be amazed by what people get stuck with. Afterwards,
you can interview the person too. It's hard work, but ultimately worth
it.

Thanks, and good luck with the project

-----------

-- 
Benjamin Humphrey

humphreybc@xxxxxxxxx
www.interesting.co.nz
www.benjaminhumphreyphotography.com