Welcome New Writers

[Shaun McCance <shaunm gnome org>]

There have been a few people introducing themselves to
the list lately, and I haven't responded to each them.
I'd like to welcome any new members of the list and
give you some pointers on how to help.

Most of our documentation is out of date.  Some of it
was never complete to begin with.  Since we have very
few active writers, you pretty much have your pick of
what to work on.

My general recommendation to new writers is to pick
an application manual for something you use frequently.
It's easier to write documentation for an application
you're familiar with.  Smallar manauls will allow you
to go through the entire writing process and actually
finish something.  Finishing things feels nice.

I've been working on a program called Pulse lately.
It basically tracks all of our software, documentation,
translations, etc.  It's not yet finished or running
continually on a production server.  But I have a test
instance running, and I try to update it frequently.

http://www.gnome.org/~shaunm/pulse/web/set/gnome-2-24-desktop/doc

That page lists all the documentation that will be
included in the 2.24 release.  Note that there may
be some modules that lack any documentation.  You
can click Modules and try to find modules lacking
documentation.

Or you might browse Programs for applications that
don't have docs.  Note that many application actually
have documentation, but they aren't linked up in a way
Pulse understands.  Going through these and linking them
would be an easy job.

You'll want to pick a document that is maintained by
the GDP at large.  One way you can know this is that
there should be a star next to "GNOME Documentation
Project" in the Developers list in Pulse.  Or you
can look at the component descriptions in Bugzilla
for docs components whose default assignee is
gnome-user-docs-maint gnome bugs 

It's a good idea to send an email to the list and
to the developers of the module if you intend to
work on something.

With an application manual, you can just try using
the application while viewing the help file.  Look
for anything that's incorrect or incomplete.

Generally, I keep three types of content in mind
when looking at an application manual:

* Exploratory
  Content which explores the functionality of an
  application.  This doesn't need to give detailed
  instructions on each feature, but it should link
  to detailed instructions.  This would be read by
  users when they're just trying to get a feel for
  the application, possibly before they even run it.

* Task-Oriented
  Content which details how to get something done.
  You want to think from a user's point of view for
  this.  Think of what actual goals the user might
  want to accomplish, and give instructions on how
  to do that.

* Reference
  Content which explains what you're seeing.  This
  is where you'd explain the elements of a dialog
  box, for instance.

When users just choose Help->Contents, they'll see
the front page of the help.  Having the exploratory
and task-oriented content is best, because that's
what users likely want.

Reference content can come later, because it will
generally be accessed by Help buttons in dialogs.
This sort of content should provide concise but
informative explanations.  Be careful not to write
"echo" documentation:

  [ ] Frobnicate my files

  Select the "Frobnicate my files" option if you
  want your files frobnicated.

Instead, try something like this:

  Select the "Frobnicate my files" option if you
  want the contents of your file to be rearranged
  randomly.  Note that this usually renders your
  files useless.  You may want to do this if you
  don't like your files.

  For more information see "Doing Useless Things"
  and "Breaking Your System".

Short and to the point, and it provides links to
task-oriented content for further reading.

Do feel free to ask for help or reviews from the
list.  I can't guarantee that somebody will be able
to respond right away.  But we are a friendly bunch,
and we really do want to help.

--
Shaun