Re: Documentation for next cycle

[Joachim Noreiko <jnoreiko yahoo com>]

--- Ryan Paul <gaerdin gmail com> wrote:

> I'm new to the GNOME documentation team, and I would
> really like to help
> out and do some work for this cycle, but I'm having
> a little bit of
> trouble getting started. I have read through most of
> the style guide and
> part of the handbook, and I guess I'm just feeling a
> bit intimidated by
> all the details. When I first decided to
> participate, I thought I would
> be able to simply jump in and start writing.
> Unfortunately, my
> experience as a journalist isn't quite as applicable
> to doc writing as I
> had initially imagined.
> 
> I think that I might be more successful if I could
> start with some
> straightforward, specific tasks. Perhaps somebody
> could give me some
> simple assignments, get me started, and help me
> avoid common pitfalls? I
> don't want to impose on anyone, but I think I'm
> going to need guidance
> in order to be productive.

Hello Ryan!
Welcome to the docs team :)

I remember all too well being intimidated by the
masses of guidelines and technical documents that
abound.
I've tried to list the bare essentials on this wiki
page: http://live.gnome.org/DocumentationProject/Join
(in point #5) but even that is a bit overwhelming.
It does cover the common pitfalls though: 
1. tone (though as you have experience as a
journalist, you should be fine with that)
2. making tons of screenshots, which is largely a
waste of time
3. using the right terms

There is a sort of newbies' paradox in that once
you've got over the initial learning curve you tend to
forget just how bad it was, and then you hopelessly
confuse the next lot of newbies by throwing out
remarks such as 'can you make me a patch for that?'
If I do that, please kick me :)

There is a list of small things that need to be done
on  http://live.gnome.org/DocumentationProject/Tasks
but looking at it now, not many of those are suitable
for just diving in.

Some things I would appreciate help on though:

* http://live.gnome.org/Gedit/Manual -- I'm using this
page to plan the structure of the gedit manual that
I'm revamping. I'd welcome any input on this.
* As part of the gedit revamp, I want to add something
to the User Guide on the absolute basics of working
with text: the insertion cursor, how to select whole
words, keyboard shortcuts for text, etc. 
* Following on from that, we UG needs a section about
the clipboard. Again, absolute basics. The intended
audience is the absolute novice, someone like my
grandmother (who was astounded when I once told her
she could copy and paste *between* different
applications).

You don't need to work with DocBook source or with CVS
to contribute -- you can just create a suitable page
on the wiki and write there.

Also, if there's anything you happen to spot that you
think needs improving, please let us know. Just an
email or a bug report saying 'Change this sentence to
this' would be fine.

Finally, track down anything that's making joining the
docs project difficult, and tell us how to improve it.

Joachim


		
___________________________________________________________ 
Does your mail provider give you FREE antivirus protection? 
Get Yahoo! Mail http://uk.mail.yahoo.com