ubuntu-manual team mailing list archive

[Matthew East <mdke@xxxxxxxxxx>]

Hi,

I agree with Phil. At the moment the boundaries of this project
haven't been as carefully addressed as I'd like, and I think that this
is the reason that this project has started up as a separate project
rather than something which comes under the general umbrella of the
Ubuntu documentation team / project. Here I think the problem we have
is that the differences between what the documentation team already
does and what the Ubuntu manual project is trying to achieve are not
clear enough.

As I've said in a previous email, I think that the main justification
for a manual that rings true to me is that there isn't currently a
single printable document that newcomers to Ubuntu can print out and
read in their own time to learn how to use Ubuntu.

At the moment I don't think the manual is intended for a different
audience, nor do I think that it aims to use a particularly different
style to the system docs. In theory topic based help such as the
system docs seeks to use a concise style that tells users simply what
they want to do. Books can sometimes use a more longwinded and
explanatory style because the user has more time and isn't trying to
accomplish a particular task when reading them. But as far as I can
see the ubuntu-manual project doesn't have a goal of writing in a
different style to the system docs, because although it has written
its own style guide, there is nothing there that indicates a different
ideology to the documentation team style guide.

There have been various criticisms of the system docs, but those
appear to me to be at best things that need to be improved in the
system docs, rather than criticisms of the aims of the system docs as
a matter of principle.

So if the only difference between what the Ubuntu docteam already aims
to produce and what the Ubuntu manual team aims to produce is one of
format, then the answer would simply be to take the existing material
in the system documentation and link it together. At most an
introductory section or some linking sections would be required in
addition.  That type of initiative would be quite maintainable,
because each release the manual could be synched with the system docs
and those working on the manual who identify errors on the material
would be able to feed that back into the system docs.

If instead there is an idea to produce a piece of documentation that
follows a book style of writing and is not as concise as the style
used by the system documentation, then I'd say that the choice is
between writing and maintaining a book from scratch, or trying to
reuse existing free content that is out there (as I pointed out here:
https://lists.ubuntu.com/archives/ubuntu-doc/2010-January/014106.html).
Trying to write a book from scratch is a huge enterprise, and requires
(as Phil has said) a careful analysis of your audience, serious
expertise and a lot of free time. I continue to have my doubts about
whether such an initiative can really succeed. It's certainly been
outside the scope of our resources historically speaking.

This project is clearly the result of a lot of enthusiasm for
documentation and for educating Ubuntu users, which is definitely a
positive thing. If we're going to focus that enthusiasm into something
which will provide a long lasting benefit to Ubuntu documentation, I'd
really like to see that enthusiasm focused into the initiative in a
way that will be maintainable in the long term and benefit the system
docs. So I think the key will be if the project is able to focus on
reusing material and giving back to the material already produced.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF