Staging notes
- extended introduction of documentation's roles
- added mallard tutorial
- mentors introduced
- pulled info/tips from Sindhu's guide
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. In writing documentation you can help with the following:
- writing, editing, updating and testing help topics for end users
- writing guides for developers
- integrating help into user interfaces
- performing help usability tests
- making high-quality instructional videos to be integrated into the help
- helping distros to use the GNOME docs as a basis for their own specific documentation
Here are some steps 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
We write new or updated docs for an application by submitting a patch using Git. This GNOME wiki page has everything you'll need to learn how to set up git, clone a GNOME project in git and 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.
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.
When selecting bugs, it's really a matter of reading description, the bug page and understanding what can be done to resolve this. This ability comes from using the application and a Gnu/Linux distribution regularly. Try selecting and reading bugs that look familiar to you. As you read bug reports, you will be able to understand terminology, issues, descriptions about that particular software better over time.
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. Follow this tutorial to learn more about Mallard.
If you don't know 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 overwhelming—but once you get set up and started you'll learn quickly, and practice makes perfect.
Get in touch
Most of us hang out in IRC, on irc.gnome.org in #docs, so you can usually get fairly quick answers (assuming you're on Europe or US time).
If you want one-on-one help, contact one of our friendly mentors!
Our previous documentation intern, Sindhu S (ingu), can also help you with technical requirements such as the tools and set-up you will need for writing documentation.
