SystemDocumentation

Revision 30 as of 2014-07-02 21:15:03

Clear message

Inclusion deadlines for ImpishString Freeze: September 16, 2021 / Non-language packs: September 30, 2021

System Documentation

One of the major tasks of the Documentation Team is to take care of the documentation which comes with every Ubuntu system. This documentation is also available on https://help.ubuntu.com/.

In order to contribute to the system documentation, you need to know a bit about the tools and processes the team uses to maintain the documentation. Don't worry if you don't know any of our tools yet. They are very easy to learn and it's possible to make useful contributions before learning how to use all the tools.

Getting Started

There are plenty of ways to get started with the team. For a quick summary of the process for each type of system documentation, refer to:

Proof Reading

An important (and easy) way of helping out is to proof-read the system documentation and report any errors that you find.

  • Follow the instructions given in the documentation to see if they work and whether they make sense
  • Click links to make sure that they still work
  • Report spelling and grammar mistakes, mis-translated words and typos
  • Report documentation that you think is missing or inadequate

You can review the system documentation on help.ubuntu.com (follow the link to the latest release to see the most up to date documentation).

See the Technical Review page for information on becoming a technical reviewer/proofreader.

Making Suggestions

You can file bug reports on Launchpad if you find a problem. See Reporting Bugs for more information on how to file bugs correctly.

Alternatively, you can make suggestions on improving the documentation on the Documentation Team mailing list.

Submitting Material

To submit new material for a particular part of the system documentation, you can simply send the text that you propose to submit to our mailing list. One of the team members will take care of adapting the text that you submit to the format that we use for System Documentation. In this way, you don't need to learn our tools to contribute regularly. However, to effectively contribute to the system documentation, you are encouraged to learn tools that the team uses.

Please remember when submitting material for transcription to DocBook or Mallard that it will take time for a member to convert your materials. In most cases, your contribution will be in the next release of Ubuntu.

It is also helpful to file a bug and post your material there. That way, we can't miss it!

Submitting Patches

To submit your work for direct incorporation into the Ubuntu documentation, you need to get hold of the raw materials that we work with. With these materials, you can make changes and submit your changes to the team.

Download the Playbook - a single sheet guide to fixing bugs!

For more details about how to contribute directly to the System Documentation, read the following sections and the pages linked there!

Repository

To make changes to the system documentation, you need to download the repository which stores the latest copy of the documentation. Like most Ubuntu projects, we store our material using the Bazaar (or bzr) version control system.

  • Detailed information on using the Bazaar branches and getting to our repository is on the /Repository page.

Docbook or Mallard?

While the serverguide is written in DocBook, the system documentation is written in Mallard. Both are similar to HTML and easy to learn and use.

  • The /Editing page details how to edit the documents.

  • The /Checking page explains how to view the files you have edited and to check your work.

Submitting Your Contribution

Once you have made a change to a document and checked your work, the next step is to send your contribution to the Documentation Team.

  • The /Submitting page explains how to send your contribution to the Documentation Team by creating a patch.

Tasks

The /Tasks page contains some ideas for working on the system documentation.