Getting Started Guide - Looking for Feedback/QA

[Ekaterina G. Potapova]

I want to add several words to the discussion, if it's possible. I'm 
quite new to Ubuntu as a whole and to DocTeam in particular. But I have 
experience in tech writing for many different companies, so I think I 
can judge a bit the quality of the Ubuntu docs. And actually since I 
started contributing, I  appreciate  greatly the way the workflow is 
organized and the way people work. So the idea that documentation is the 
weakest point and that it needs some revolutionary changes seems to me 
very doubtful or even absurd.
Thanks,
Katya

Avi Hein wrote:
>  
> 
>> OSS Watch - http://www.oss-watch.ac.uk/resources/documentation.xml
> Actually, this is an article about docu mentation 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.
> 
>