Re: Troubleshooting

[Paul Cutler <pcutler gnome org>]

Kevin,

On Mon, 2010-03-29 at 14:53 -0600, Kevin Pomeroy wrote:
> Hi,
> My name is Kevin and I am new to the GNOME Documentation Project. i am
> excited to be involved and I hope this is the proper place to be
> writing stuff at. 

Welcome!  Thanks for introducing yourself via email.  We like to think
we have an open and welcoming community.
> 
> Being new, I'm not sure what has been discussed in the past and what
> things have been decided. But from my perspective as an end user when
> I used Windows for most of my life before switching to Linux a couple
> years ago, the main time I would refer to the documentation and
> manuals was when I was have a problem or error and couldn't fix by
> messing with it. I noticed looking at some of the user guides for the
> programs that they lacked a general trouble-shooting section, which I
> feel would be very useful to new users. Since Linux can be
> significantly more complicated then a PC/Mac setup and have more areas
> where problems can occur, it may be a good idea to highlight some of
> the most common problems and ways to solve them. Just an idea, I'm
> sure it has been brought up in the past though.

Absolutely agree with your idea above.  In fact, now is a great time to
get involved as we are in the process of transitioning a lot of the
existing (and new) help to topic based help - and one of the topics
we're looking to add to our documentation is common problems /
questions.  For an example of what our new help looks like, including
Common Problems, check out Empathy's help.

> 
> Being involved in writing for a good part of my life, I am glad I can
> help take part in a small way being involved in the Linux community.
> Yesterday i found a typo and submitted my first bug report, not a big
> error but it was something. I will probably focus on proof-reading and
> editing for the time being, but in case I were to be involved with the
> writing aspect, is there a simple way of determining what parts of
> manuals/user guides that need to be completed?

Awesome!  Thanks for submitting the bug report.  We are always looking
for help.  Here are some resources to help you get started:

Our homepage / wiki:  http://live.gnome.org/DocumentationProject
Style guide:  http://library.gnome.org/devel/gdp-style-guide/2.30/
(Still pretty up to date, even though we should update it to focus more
on topic based help, but chapters 4 - 10 are very relevant.  
Mallard:  We're moving away from DocBook as the XML language we use to
write help and moving to Mallard (http://www.projectmallard.org).  If
you haven't used either before, I can guarantee you'll find Mallard ten
times easier than DocBook.

To answer your question though on what manuals and user guides need to
be completed?  Almost all of them.  We have plans to replace the entire
user guide in GNOME 3.0 this September, which will be a huge group
effort.  As we move to topic based help, almost any help in GNOME with
the exception of maybe 5-6 applications need new help.  The best advice
I can give you is if you're looking to write help is to pick an
application you're familiar with and like.  We are more than happy to
help you from there, including planning, writing, editing and more.  I
know it's a vague answer, but honestly - write what you know!  We can do
collaboration on the GNOME wiki for planning, Google Wave or other
tools.

We're also big on using IRC in addition to this email list for
communication.  If you're looking for a place to hang out and talk docs,
download your favorite IRC client (xchat-gnome, irssi etc) and join the
GIMPNet network, we're in #docs.  We also have weekly meetings on
Sundays at 17:00 UTC / 12:00 pm. US CST if you can join us in IRC.

I look forward to working with you.  (And off to find your bug!)

Paul