Ubuntu Wiki

Ubuntu Open Week - Contributing to Ubuntu Documentation - Dougie Richardson - Fri, Nov 7th, 2008

(04:02:19 PM) DougieRichardson: Hi all
(04:02:56 PM) DougieRichardson: I'm here to discuss contributing to Ubuntu's documentation
(04:03:13 PM) BenC left the room.
(04:03:44 PM) DougieRichardson: The first link you need to get started is https://wiki.ubuntu.com/DocumentationTeam
(04:04:32 PM) DougieRichardson: Documentation is split into two main areas - system help and online help
(04:05:07 PM) DougieRichardson: System help is written in DocBook XML and packaged with each release.
(04:05:44 PM) DougieRichardson: Online help, again is split into two areas: help.ubuntu.com which is built from the system documentation
(04:06:17 PM) DougieRichardson: and help.ubuntu.com/community which is where the community contributed wiki docs are
(04:06:51 PM) DougieRichardson: So how do you start conributing?
(04:07:40 PM) DougieRichardson: The easiest place to start is by proof reading. Checking through the system documentation and picking up on errors.
(04:08:48 PM) DougieRichardson: The team itself is split into two groups - committing members and students.
(04:09:52 PM) DougieRichardson: the only difference being that committing members push patches into the current branch.
(04:10:23 PM) DougieRichardson: As a student, you are assigned a mentor to guide you.
(04:11:17 PM) DougieRichardson: The current source can be downloaded from Launchpad
(04:11:47 PM) DougieRichardson: using bzr
(04:12:53 PM) DougieRichardson: https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository
(04:14:01 PM) DougieRichardson: Once you have a copy of the docs, the best place to get started is by looking for bugs listed on launchpad
(04:14:47 PM) DougieRichardson: There are two places to look: https://bugs.launchpad.net/ubuntu/+source/ubuntu-docs for bugs reported against the package
(04:15:26 PM) DougieRichardson: And https://bugs.launchpad.net/ubuntu-doc for the team
(04:15:59 PM) DougieRichardson: So lets talk through a typical bug, by following https://bugs.launchpad.net/ubuntu-doc
(04:16:56 PM) DougieRichardson: From the filter panel, we click "new"
(04:17:22 PM) DougieRichardson: Lets look at the techreview bug 235079
(04:18:10 PM) DougieRichardson: Here we have a list of corrections that someone has spotted, so we can go right ahead and start correcting them.
(04:19:27 PM) DougieRichardson: The first issue is to find out which file you need to edit - so open a file browser window and navigate to the ubuntu-docs folder
(04:20:00 PM) DougieRichardson: This case is apparent - its in programing
(04:20:22 PM) DougieRichardson: All folders will have two sub-folders, PO and C
(04:20:32 PM) DougieRichardson: PO is for translation, so we need to be in C
(04:21:08 PM) DougieRichardson: Now we can edit the programming.xml file by opening it, looking for the error and amending it.
(04:21:26 PM) DougieRichardson: So now we have a corrected version locally, we need to submit it to the team.
(04:22:21 PM) DougieRichardson: First though we will check that they are valid and will not break the package.
(04:23:18 PM) DougieRichardson: From the ubuntu-doc folder, run scripts/validate.sh index.xml
(04:23:36 PM) DougieRichardson: We need to run it on the root because otherwise it will pick up errors from linked files.
(04:23:58 PM) DougieRichardson: OK so it validates, now we create a patch to submit.
(04:24:37 PM) DougieRichardson: This involves just two commands:
(04:25:06 PM) DougieRichardson: bzr commit -m "Describe the change, include a bug number"
(04:25:30 PM) DougieRichardson: bzr bundle > diffname.txt
(04:26:30 PM) DougieRichardson: Or, if its just a small patch then bzr diff > patch.txt will do
(04:26:56 PM) DougieRichardson: Add a comment to the original bug attaching your patch and you've fixed your first bug.
(04:27:16 PM) DougieRichardson: So that brings us on to the second area we work on - the community docs.
(04:27:54 PM) DougieRichardson: As long as you have a Launchpad account, you can add and edit community documentation
(04:28:23 PM) DougieRichardson: http://www.ubuntu.com/community
(04:28:46 PM) DougieRichardson: Sorry - http://help.ubuntu.com/community
(04:29:19 PM) DougieRichardson: The best way to approach assisting on the wiki is to look up subjects you are familiar with.
(04:29:37 PM) DougieRichardson: If there is already a page, then you can proof read it for errors and improve it.
(04:29:45 PM) DougieRichardson: Otherwise you can create a page.
(04:30:09 PM) DougieRichardson: We just ask that you read the first page and follow the guide.
(04:30:29 PM) DougieRichardson: Both types of documentation are under a creative commons licence
(04:31:59 PM) DougieRichardson: Well that about covers it, so we'll move on to questions now. Remember that the largest problem that we have as a team is getting enough contributers. This is especially true for the wiki where we would love to get all the fantastic community howtos that are out there centralised.
(04:32:10 PM) DougieRichardson: So, lets take questions now.
(04:35:20 PM) DougieRichardson: OK, what are the main areas that still need work?
(04:35:55 PM) DougieRichardson: For the community docs, we would like to import as much from the forums as possible.
(04:36:17 PM) DougieRichardson: This requires that we get the permission of the original writer.
(04:36:34 PM) DougieRichardson: So if you see a great guide, nudge the writer to submit it to the team.
(04:37:22 PM) DougieRichardson: Our mailing list is here: https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
(04:37:04 PM) ssole: how do you manage translations?
(04:37:39 PM) DougieRichardson: Translations are managed by Matthew East
(04:38:08 PM) DougieRichardson: The best place to start is https://wiki.ubuntu.com/DocumentationTeam/Translation
(04:38:35 PM) DougieRichardson: We use Rosetta
(04:39:00 PM) DougieRichardson: About two or three weeks before release, we eter string freeze.
Then the translators have a chance to translate all the changed strings for release.
(04:40:16 PM) DougieRichardson: I have to go in a few minutes, so I'd like to wrap up here.
(04:40:27 PM) DougieRichardson: Are there any more questions?
(04:41:39 PM) DougieRichardson: OK, The main link to remember is https://wiki.ubuntu.com/DocumentationTeam
(04:42:18 PM) DougieRichardson: If you can contribute any time or docs to us, or recommend any for us to follow up - its greatly appreciated.
(04:42:35 PM) DougieRichardson: Thanks for your time and I'l hand back over to jcastro now