Getting Started Guide - Looking for Feedback/QA

[AviHein at gmail.com]

As I stated, I wasn't referring specifically to Ubuntu or the DocTeam but a  
general issue in open source. As I mentioned before, other Linux  
programmers and journalists have mentioned this. Forget I said that, I look  
forward to contributing to Ubuntu.

On Feb 17, 2009 10:47pm, "Ekaterina G. Potapova" <egeomar at mail.ru> wrote:
> 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.
>
>
>
>
>
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20090217/7cb798d3/attachment.html>