Getting Started Guide - Looking for Feedback/QA

[Dougie Richardson]

AviHein at gmail.com wrote:
> I apologize if anyone was insulted. Ubuntu's documentation is some of 
> the best open source documentation I have seen. I'm hoping we can take 
> professional tech comm to a new level in open source. But, my point 
> was that great products in open source often don't have great 
> documentation -- this is not something from me but other sources such as:
>
> That is, open source documentation faces unique challenges. I hope 
> that we can together overcome these challenges for the benefit of 
> Ubuntu and to advance its popularity among the non-developer, non-tech 
> community and I hope my guide (and the future work that I will do, 
> including edits to the Wiki, etc.) will help overcome these challenges 
> within Ubuntu and the Linux community.
>
> OSS Watch - http://www.oss-watch.ac.uk/resources/documentation.xml
Actually, this is an article about documentation in general and 
discusses issues on management.
> Is Documentation Holding Open Source Back? - 
> http://www.devx.com/opensource/Article/11839
This is arguably an article discussing HCI principles rather than 
managing or writing documentation. Its also almost entirely mute because 
it neglects the fact that the predominant method for new users is to 
Google rather than follow a document hierarchy. He also repeatedly 
states that its an unscientific and unstructured approach to appraising 
documentation.
>
> Linux.com wrote about the admirable FLOSS manual project 
> (http://www.linux.com/feature/155205): "Documentation is one area in 
> which free/libre/open source software (FLOSS) is weakest." That is 
> what I meant, but we are working to improve this.
>
Don't even get me started on this.  I had dealings with this project in 
the last run of the Desktop Training Team and their documentation is not 
really any different to ours.  Its just the delivery method that is 
better (at least until Moin supports PDF generation on the fly).
> Much work has been done to improve these challenges, and so instead of 
> attacking a poor phrasing of words, let's collaborate together, using 
> professional standards, to improve the quality of Ubuntu's documentation.
Its not an attack, wording is the crux of what we do!
>
> I apologize if anyone was offended and eagerly would ask for your 
> feedback to improve the guide that I wrote (which will, in parts, be 
> added to the community supported documentation and if anyone has 
> suggestions for adding this to the official or community supported 
> documenation either bundled with Ubuntu or on the website, I would be 
> most grateful).

As Johnathon said, I'm not sure where this fits in and it is very 
similar to large chunks of the system documentation and the switching 
from windows guides.

I am worried that you listed this as your copyright - draft or not, 
there are some very strong similarities to areas of our official 
documentation.

That said, there are good points and the only real niggles with what 
you've done are:
1. Kubuntu users are going to have a field day when they read the line 
"Ubuntu uses the GNOME desktop environment" - I know what you mean but 
I'd suggest mentioning from the out set the difference between K/X/Ubuntu.
2. The book is very heavy on images, how do you plan to manage this for 
translation?

Dougie