Ubuntu Wiki

Ubuntu Documentation - Desktop Getting Started

Introduction

Ubuntu is all about community collaboration and the work we do together in order to produce a reliable world-class operating system. The same standards that apply to contributing to Ubuntu generally apply to contributing to Ubuntu Documentation.

Ubuntu Documentation is maintained by the Ubuntu Documentation Contributors Team with commit rights and administration by the Documentation Committers team and this page describes how you can start the journey of contributing to Ubuntu Documentation.

sudo apt install bzr xsltproc libxml2-utils yelp-tools yelp-xsl make

sudo apt install gnome-user-docs* gnome-getting-started-docs*

sudo apt install docbook docbook-xsl

sudo apt install fop gnome-doc-utils

ssh-keygen -t rsa

bzr whoami "Bob Dobbs <subgenius@example.com>"
bzr launchpad-login subgenius

sudo apt install bzr-explorer

Getting a copy of the documentation development branch

The first step you will want to take to begin working on Ubuntu Documentation is to download a copy of the development branch of Ubuntu Documentation using Bazaar:

bzr branch lp:ubuntu-docs

Now that you have a local copy of Ubuntu Documentation you will want to become familiar with the anatomy of the Ubuntu Documentation branch. Mallard files will always be found in the path

~/ubuntu-docs/ubuntu-help/C.

Building html version of the docs

If you wish to just build the documentation as html to review them, follow these steps with your checked out branch:

cd ubuntu-docs/html/
make

The resulting documentation will end up in ~/ubuntu-docs/html/build/en/ which you can view in your web browser. More information on building the docs.

Changing the help

Changing the help is sometimes as simple as opening the Mallard files in a command-line based text editor and reviewing them for minor changes like updating version numbers to the upcoming release number or checking for spelling and grammar. In other cases for topic-oriented pages, it may be necessary to ensure that features have not significantly changed and if they have then to update the documentation accordingly to reflect those changes.

The process of changing the help is typically as follows:

• Check your copy of the development branch is up-to-date using bzr pull.
• Change the help files.
• Check that the help files validate as proper Mallard markup code.
• When you're happy with your changes and you're ready to create a new revision, again check your copy of the development branch is up-to-date using bzr pull.

• If you don't want to keep your last revision, you can cancel it using bzr uncommit. In this case if you upload a new revision to an existing personal branch you must use bzr push with the --overwrite option.

• Create a new revision using bzr commit.
• Upload your revision to a personal branch on Launchpad using bzr push.
• Propose a merge of your revision into the development branch.
• Once approved your revision will be merged into the development branch.

The rest of this section gives more details of validation, bzr commit, bzr push and the merge proposal.

To check if the Mallard synax is ok, you should make sure that the current directory is ubuntu-help/C and run this command:

./validate.sh

As regards the bzr commands below, the current directory should be the branch root.

The bzr commit command might be as follows:

bzr commit -m 'Brief one sentence summary of change goes here'

or if there is a related launchpad bug:

bzr commit --fixes lp:123456 -m 'Brief one sentence summary of change goes here; LP: #123456'

or if there are multiple related launchpad bugs:

bzr commit --fixes lp:123456 --fixes lp:123457 --fixes lp:123458 -m 'Brief one sentence summary of changes goes here; LP: #123456 LP: #123457 LP: #123458'

The bzr push command is as follows:

bzr push lp:~<username>/ubuntu-docs/<revision-name>

You propose your changes for merging by going to the Code section of your Launchpad account, selecting the appropriate personal branch, and submitting a merge proposal ("Propose for merging"), or by running:

bzr lp-propose

(This command will open your default web browser and, if you have granted Bazaar permission to interact with Launchpad, it will submit a merge proposal.)

Creating Personal Sandbox Branch

If you log in to Launchpad and click the Code link at the top of the page, it will give you a bzr push command you can use to upload your sandbox work. Change BRANCHNAME in that command to whatever you want to call the sandbox you'd like to upload.

Since uploading to your own repo is standard practice for folks who aren't part of the core committers team, under "Submit your changes for review" there can be a note after `bzr push' saying that this can be used for simply "saving" your work in your own branch prior to merging as well.

What's next

This documentation is intended to be introductory but you can learn much more about Mallard through their own tutorials. You can always ask for help on Ubuntu Documentation Team’s mailing list or on #ubuntu-doc on Freenode IRC.

We look forward to seeing your contributions to Ubuntu Documentation and answering any questions that you may have.

Discussion

NOTES
I think that there is too much information, to the point where it gets confusing for the user reading it. To solve this, you could 1) Split the information into new, separate pages. 2) Remove some information that is not that useful - for example in the 'Get a Launchpad account' there is a lot of info which could be reduced to just the launchpad link together with a brief sentence to go with it, as in my opinion creating a launchpad account is pretty straightforward. By doing this in some sections, you could greatly lower the amount of info, which would allow the user to understand the guide better.