Documentation Team ยป

Contributing to the GNOME Documentation Project

Writing documentation can be a great way to build the open source community, discover how open source software is created and meet the people who make it happen. There are different ways in which you can help, depending on your level of technical knowledge. Here are some different things to do to get started:

Read the GNOME Documentation Style Guide

The GNOME Documentation Style Guide will give you an overview of grammar usage, writing for an international audience, correct GUI terminology, writing accessibility documentation and other topics. NOTE: This guide is currently being brought in-line with GNOME's modernised approach to help, so some parts may be somewhat outdated, but it is still a worthwhile study for beginners.

Set up your development environment using Git

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. This GNOME wiki page 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).

Pick a project

You can start by either fixing little things filed as bugs in gnome-user-docs in GNOME Bugzilla or contributing to an existing project. The GNOME Git page linked above explains how to clone a GNOME project in git.

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.

Pick a Mark-up language

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. You can learn more about Mallard at its website, including code samples and examples.

If you don't understand Mallard, you can also write documentation in plain text and add it to a bug in Bugzilla. It may take us longer to add the markup and commit the new documentation, but it's also an option.

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. We recommend making the process as collaborative as possible - email the Docs list with your topic ideas, use the planning page on the Docs wiki where you can see some brainstorming examples, 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.

Write, Write, Write

And edit, edit, edit.

And license.

And take screenshots.

And pay attention to translations.

And spellcheck.

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.

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, on in #docs, so you can usually get fairly quick answers (assuming you're on Europe or US time).


TiffanyYau/Staging/DocumentationProject/Contributing (last edited 2013-12-03 19:04:41 by TiffanyYau)