Getting Started Guide - Looking for Feedback/QA

[Avi Hein]

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

--> As I mentioned, my comments were not meant to refer to Ubuntu's
documentation but rather a general statement that appears to be recognized
today in the open source community. I hope to be able to help contribute to
it, as I am a strong believer in the Ubuntu philosophy and the idea of a
desktop-friendly distribution of Linux.

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

--> I am releasing the final version of this specific doc under the GNU Free
Doc license. It's the same license as GIMP's release. Obviously it wouldn't
impede the official doc or anything anyone else has ever written.

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?

--> Regarding point 1, I'm thinking about that but how do I do that without
creating a separate doc for Kubuntu? I haven't used Kubuntu or the other
versions, but would the procedures be different? I think it can be easily
modified for X/Kubuntu. I'm more than open to suggestions.

Regarding #2, you're right and on the basis of your suggestion, I can (and
should have initially had it this way) change the desktop screenshot to
numbering, which is the common way of doing this for localization. I should
have done that initially and so thank you for pointing this out. Regarding
the screenshots, I'm not sure how I can fix that except that a localizer can
redo them. In general, I was taught that it's good to use images and
screenshots but you raise a very good point.

Thanks for suggestions and I will also be happy to make any edits to the
official or community documentation that I can be of assistance on.