What is best for the documentation?

[Jeff Schering]

Howdy folks,

Here's a mild rant, but it ends with an idea or two on how we can move
forward...

The docteam is small in number, and its contributors have day jobs and
other pressures and pleasures of day-to-day life. As a consequence,
there is not a lot we can get done from one release to the next. If we
each have only a couple of hours per week to give to the
documentation, then it's understandable that our work is incomplete
and in almost total disarray. A further complication is that like
typical humans, we spend more time bitching and complaining than we do
writing.

In my opinion, we should approach the task of conflict resolution by
asking ourselves the following question:

"Is it good for the documentation?"

That's one of the reasons why we're all here, isn't it? To make good
documentation so that the users of Ubuntu and its documentation are
helped by us.

So, what is good for Ubuntu documentation?

1. First and foremost, the writers must know the audience. We must
know who they are, what they already know, and what they want to know.
David Ottina has done some good work in this direction.

2. The documents must be factually correct.

3. The reader needs to have a good impression of the professionalism
of the documentation -- this leads to confidence in the product.
Shoddy docs drive users away.

IMHO (I'm open to argument) it's better to have a tiny amount of
complete, correct, and professional documentation than it is to have a
large amount of incomplete and "work in progress" documentation.

Our User Guide is a work in progress, and I'm pretty sure that we will
be very lucky to have it ready in time for breezy+2, let alone breezy
itself. The reason why I think it won't be ready is due mostly to a
lack of time for any of the members of our little team to work on it.
It will take more hours to complete than we have available.

With the idea in mind that it's better to have a small number of
complete docs, I see something that we just might be able to do in
time for breezy if we all concentrate on it to the exclusion of all
other docteam projects. It means that when somebody asks "Where can I
help?", we answer "Section so-and-so of Local Help" instead of
"Wherever you want."

Much of the info (if not all of it) for Local Help already exists in
the faq guide, the user guide, the quick guide, the forums, and the
wiki. It's simply a matter of collecting and consolidating it into
Local Help.

To be clear, this is the menu on the proposed top page of Local Help:

* If you're new to Ubuntu 5.10
* Customizing settings
* Internet and networking
* Working with files from Windows
* Documents, files, and folders
* Disks and devices
* Music, photos, and video
* Printing and faxing
* Keeping your computer safe
* Maintenance and troubleshooting
* Advanced topics
* Getting more help

I think if we concentrate our efforts on this, we can get it done by
string freeze. It will be best for the documentation, and it will be
best for the users of Ubuntu. If time does get short then we can leave
off the "Advanced topics" section -- advanced Linux users are
accustomed to missing documentation.

It will get done faster if it's done in svn instead of bazaar, and it
will get done faster if we stick to the current dual licensing scheme.
IMHO, it's best to leave discussions about bazaar and licensing until
after breezy. The time for sweeping changes in process is after
release, not 5 weeks before string freeze.

This is just a suggestion on my part -- I am not emotionally tied to
anything in it -- it's just my opinion of what's best for Ubuntu
documentation. Agree or disagree, but before you do either one, ask
yourself "Is it good for the documentation?"

Cheers,
Jeff

-- 
GPG Key: 1024D/F23C67E8 2005-02-20 Jeff Schering <jeffschering at gmail.com>