SystemDocumentation

Differences between revisions 14 and 15
Revision 14 as of 2009-08-06 22:38:57
Size: 4689
Editor: host81-155-28-70
Comment:
Revision 15 as of 2010-03-23 05:57:41
Size: 4818
Editor: mvngu
Comment: fix some typos; clean up grammar
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
One of the major tasks of the DocumentationTeam is to take care of the documentation which comes with every Ubuntu system, and is available from '''System''' -> '''Help and Support''' on an Ubuntu desktop. It is also available on https://help.ubuntu.com. One of the major tasks of the DocumentationTeam is to take care of the  documentation which comes with every Ubuntu system, and is available from '''System''' -> '''Help and Support''' on an Ubuntu desktop. This documentation is also available on https://help.ubuntu.com.
Line 5: Line 5:
The team also takes care of the system documentation available in Kubuntu, Xubuntu and Edubuntu and the Ubuntu Server Guide. The team also takes care of the system documentation available in Kubuntu, Xubuntu, and Edubuntu as well as the Ubuntu Server Guide.
Line 19: Line 19:
 * Follow the instructions given in the documentation to see if they work and if they make sense  * Follow the instructions given in the documentation to see if they work and whether they make sense
Line 34: Line 34:
If you'd like to submit some new material for a particular part of the system documentation, and don't want to learn our tools to contribute regularly, you can simply send the text that you propose to submit to our [[DocumentationTeam/Contact|mailing list]]. One of the team members will take care of adapting the text that you submit to the format which we use for System Documentation. To submit new materials for a particular part of the system documentation, you can simply send the text that you propose to submit to our [[DocumentationTeam/Contact|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 DocumentationTeam uses.
Line 36: Line 36:
Please remember when submitting material for transcription to DocBook that it will take time for a member to convert it, in most cases it will be in the next release of Ubuntu. Please remember when submitting material for transcription to DocBook 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.
Line 38: Line 38:
If you like, it is also helpful to [[https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs|file a bug]] and post your material there. That way, we can't miss it! It is also helpful to [[https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs|file a bug]] and post your material there. That way, we can't miss it!
Line 40: Line 40:
If you'd like some ideas about what material to contribute, see the [[/Tasks]] page. For more ideas about what material to contribute, see the [[/Tasks]] page.
Line 44: Line 44:
If you'd like to submit your work for direct incorporation into the Ubuntu documentation, you need to get hold of the raw materials that we work with, make some changes, and submit them to the team. 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.
Line 48: Line 48:
If you'd like some more detail about how to contribute directly to the System Documentation, read the following sections and the pages linked there! For more details about how to contribute directly to the System Documentation, read the following sections and the pages linked there!
Line 52: Line 52:
If you want 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: 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.
Line 54: Line 54:
 * Detailed information on on using the bazaar branches and getting to our repository is on the '''[[/Repository]]''' page.  * Detailed information on using the Bazaar branches and getting to our repository is on the '''[[/Repository]]''' page.
Line 58: Line 58:
The system documentation is written in a simple markup language called Doc``Book XML. Doc``Book is similar to HTML and is easy to learn to write with. When you start working on our documents, you will see how Doc``Book is employed by the docteam. The system documentation is written in a simple markup language called Doc``Book XML. Doc``Book is similar to HTML and is easy to learn and use. When you start working on our documents, you will see how Doc``Book is used by the DocumentationTeam.
Line 63: Line 63:
== Submitting your Contribution == == Submitting Your Contribution ==
Line 71: Line 71:
You can get some ideas for tasks that need doing on the system documentation on the '''[[/Tasks]]''' page. The '''[[/Tasks]]''' page contains some ideas for working on the system documentation.

One of the major tasks of the DocumentationTeam is to take care of the documentation which comes with every Ubuntu system, and is available from System -> Help and Support on an Ubuntu desktop. This documentation is also available on https://help.ubuntu.com.

The team also takes care of the system documentation available in Kubuntu, Xubuntu, and Edubuntu as well as the Ubuntu Server Guide.

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.

The first thing you need to do is familiarize yourself with the docteam environment. This page briefly describes the various things you need to know and provides links for further reading and discovery.

Getting Started

There are plenty of ways to get started with the team.

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

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 materials 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 DocumentationTeam uses.

Please remember when submitting material for transcription to DocBook 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!

For more ideas about what material to contribute, see the /Tasks page.

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

The system documentation is written in a simple markup language called DocBook XML. DocBook is similar to HTML and is easy to learn and use. When you start working on our documents, you will see how DocBook is used by the DocumentationTeam.

  • 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 DocumentationTeam.

Tasks

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

DocumentationTeam/SystemDocumentation (last edited 2015-01-09 18:41:02 by petermatulis)