Improving Ubuntu Help/Docs part 1 of 3

[David Tangye]

On Fri, 2006-04-28 at 10:12 +1000, David Tangye wrote:

> Part 2: Quality and why you wont get this stuff right unless you
> understand and adhere to the formal concepts of "Quality". I hope to
> make that part shorter than this one.
> ... If I say that there are "four plus one" cornerstones of
> Quality, what is the single most important fundamental one.

OK, no one confident enough, or interested enough? to have a go at the
answer?

*** Customer focus. ***

The key to everything you do professionally.

It should have enormous bearing on everything you do at work, and
inasmuch as your work here is voluntary, it makes no difference to the
fact that Ubuntu needs customers.
Refer https://launchpad.net/distros/ubuntu/+bug/1 - Its all about
getting customers, and dozens of comments lamenting that M$ STILL has
the market pretty much sewn up.

As far as documentation goes writers need to constantly review their
work, asking the single question each time they work on a Wiki page or
Doc, "How is that going to do down with our customers?" Subquestions in
order of importance:

 1. When they FIRST open the page, right at the start, does it set the
scene? / give a high level overview? etc Does the top heading DIRECTLY
address the topic that the customer clicked on to get here? [Set the
context]
 2. Does this document/page state UP FRONT and EXPLICITLY what level of
technical expertise or prior knowledge is assumed/needed? [State the
audience]
 3. When they read the document/page, where MIGHT they conceivably get
lost. How can I put something in to try to avoid that? [Be helpful]
 4. If the customer knows little about this sort of thing, will this
document/page CLEARLY, CONCISELY, UNAMBIGUOUSLY give a FULL yet FOCUSSED
answer/description? Or will they probably get lost. [Produce excellence]

Look back at docs you have changed. I have. Do they measure up? I have
seen quite a few that do, and many, including key ones, that simply do
not.

Of course there is an implicit question that needs to be addressed and
ANSWERED, before you can adequately answer the above questions. Part 2B,
coming shortly, what is that question? It's vital to where Linux and
Ubuntu is going, or not.

ps: Thanks for messages of advice regarding Part 1: responded to
privately in some cases.