ubuntu-manual team mailing list archive

[Benjamin Humphrey <humphreybc@xxxxxxxxx>]

I'm not going to bother typing out a huge email to answer your criticism.
I'm a bit too busy for that right now. The wiki contains more than enough
information for you anyway.

If you don't believe that this project will be successful, then
unfortunately that is your problem - I wrote a very nice email to the docs
team expressing interest to collaborate and offered you basically unlimited
use of our resources and material, but the reply I get still doubts our
project - fair enough, if that's how you feel then you'll have to wait and
see.

On Thu, Jan 14, 2010 at 11:35 AM, Matthew East <mdke@xxxxxxxxxx> wrote:

> 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
>



-- 
Benjamin Humphrey

Ubuntu Manual Project Leader
Dunedin, New Zealand

https://wiki.ubuntu.com/ubuntu-manual
www.interesting.co.nz
www.benjaminhumphreyphotography.com