Re: gdp

[Paul Cutler <pcutler gnome org>]

On Mon, 2010-06-28 at 18:24 -0400, Tiffany Antopolski wrote:
> Hi,
> 
>   I am a fourth year software engineering student, and I am very
> interested in getting involved in GDP.  I would like to write new
> documentation for applications in need of new or updated user docs (I
> think this would be a good place to start).  However, I don't really
> know how to go about getting involved.
> 
>   I was just reading through the Documentation Project pages on
> live.gnome.org.  How would I actually start participating in
> contributing to the project if I was interested in writing user docs for
> one of the apps listed there (for example Evince).  Who would I contact?
> 
>  At the moment I do not have any experience with open-source (except for
> being a ubuntu user).  Any guidance, advice, help, or being pointed in
> the right direction would be greatly appreciated.
> 
> I am 'mimico' on irc.  Hope to see you there.
> 
> Thanks and cheers,
> 
> Tiffany Antopolski


Hi Tiffany,

Thanks for introducing yourself via email and wanting to help out with
GNOME documentation.

I apparently have a new project for the weekend, as our Contributing
page on the wiki is out of date.[1]

If you're interested in writing docs, a few things to check out:

1.  Review the GNOME Documentation Style Guide. [2]

While some pieces of it are out of date, the sections on grammar,
international audiences, GUIs, usability and accessbility are really
good.  

2. Set up your environment using Git [3]

You'll want to learn some Git basics - the easiest way after writing new
or updated docs for an application is to submit a patch using git.  The
wiki page above has everything you'll need to set up git and how to
create a patch when you're ready.  (Depending on the Linux distribution
you use, you may have to install git).

3. Pick a project

You can start by either fixing little things filed as bugs in
gnome-user-docs in GNOME Bugzilla[4] or start writing new help for an
existing application (you mentioned Evince above).

Either way, you'll want to do a git checkout of the application you're
going to work on and submit a patch with your changes in GNOME Bugzilla.

4. Pick a language

If you're working on updating existing documentation, chances are it was
written in Docbook.

If you're working on new documentation, we recommend Mallard.  

We are transitioning to topic based help - small chunks of help that
focus on one thing and help the user get the help they need faster.  

The Mallard language was created specifically for topic based help - not
only does it have an easier syntax to learn than Docbook, it will help
in creating topic based help and linking to other topics.

Now is a great time to join the Docs team as we're just starting this
process - last fall Empathy's help was written in Mallard and this past
March in GNOME 2.30 more applications adopted it, including Brasero,
Cheese, and a couple more I'm forgetting.  Tomboy's new Mallard help was
integrated just today and Rhythmbox and Bansee are under active
development too.

Which means that almost any GNOME application could use new help written
in Mallard, so we're going to be busy.  :)

One other change is we're using a new license for help (Creative Commons
CC-BY 3.0 instead of the GFDL) which means in almost all cases we have
to write new help from scratch.  (Which is fine as topic based help is
organized differently).

5. Plan your writing

The hardest part in writing documentation is thinking about what you're
going to write about.  Since we're doing topic based help, you will need
to brainstorm all of the topics you think should be included in the
help, and then brainstorm some more.  I recommend making the process as
collaborative as possible - email the Docs list with your topic ideas,
use the Docs wiki where you can see some brainstorming examples[5], and
also reach out to the application's developers with the list too.  Join
the app's mailing list and follow along of what is actively in
development. 

6. Write, Write, Write

And edit, edit, edit.

7. Get reviews

As you progress, get peer reviews.  Ask in #docs in IRC or on the
mailing list - we're here to help and like to think we have an open and
welcoming community.  (Though IRC you might have to wait a bit
sometimes).

Before help is considered final, we ask for a peer review from the docs
team and a review from the application's developer team.

8. Have fun!

This may sound like a lot of stuff - but once you get set up a lot of it
will come to you, and practice makes perfect.  Most of us hang out in
IRC so you can usually get fairly quick answers (assuming you're on
Europe or US time).  

Thanks again for the email and let us know if you have any questions.

(And if I've missed anything, Shaun, Phil or Milo can add more!)

Paul


[1] http://live.gnome.org/DocumentationProject/Contributing
[2] http://library.gnome.org/devel/gdp-style-guide/stable/
[3] http://live.gnome.org/Git/Developers
[4] https://bugzilla.gnome.org/browse.cgi?product=gnome-user-docs
[5] http://live.gnome.org/DocumentationProject/Planning