Ubuntu Documentation Processes

[Matthew East]

Hi Elizabeth,

I'm copying this message to the ubuntu-doc list for reference
purposes. For context, Elizabeth asked a few general questions about
the ubuntu-docs processes with a view to preparing some information
for contributors. I'm doing my best to answer the questions below,
although to the extent that I'm cross referencing to out of date wiki
pages, I appreciate that such an answer is necessarily incomplete. As
noted on another thread, I'll try and update the wiki pages over the
next few weeks.

> From: "Elizabeth Krumbach" <lyz at ubuntu.com>
> For my first item I'd like to get a clearer picture
> about the system documentation process:
>
> 1. Where docs live (I couldn't find quantal or raring branches for
> ubuntu-docs, it's very confusing. In spite of working with the Xubuntu
> folks on docs, I don't actually know how flavors make a new docs
> package for a new release)

The Ubuntu desktop docs live in the ubuntu-docs project on Launchpad.
There is also an umbrella project named "ubuntu-doc" which should
contain all the flavours. In terms of how new packages are made, this
is essentially the same as the workflow on any Launchpad project which
hosts code in bzr: a new bzr branch is created from the previous one,
and it is linked to a release series in Launchpad. Launchpad has
documentation on this. The bzr branch contains the Ubuntu source
package, this is uploaded to the distribution in the same way as any
Ubuntu package.

> 2. Loosely how people contribute to it (uses mallard? do all flavors
> use similar tools? stored in bzr, so do they branch, fix and submit a
> merge proposal?)

In terms of how to contribute using bzr, the relevant documentation is
here (probably out of date):

https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/Repository/Members

In terms of markup language: flavours do use different markup
languages, because ubuntu-docs uses Mallard and most other flavours
use Docbook. That necessarily means that some different tools are used
to build and translate documentation. ubuntu-docs has adopted exactly
the same toolchain as Gnome Docs for simplicity, because these tools
are optimised for use with Mallard. The other flavours use toolchains
that were hacked together over an evolutionary period of years, which
are defined in a series of scripts and Makefiles contained in the
source package. They are documented here (again, probably out of
date):

https://wiki.ubuntu.com/DocumentationTeam/Translation
https://wiki.ubuntu.com/DocumentationTeam/SystemDocumentation/BuildingDocumentation

As discussed on the other thread, I'll try to update these. So far the
Mallard tools are not documented, partly because the pages have been
abandoned for some time, and partly because they are Gnome-standard,
but I will try to add relevant information and links there. It will be
quite tricky to document the processes for ubuntu-docs alongside the
processes for the other flavours on the same pages, but I will try to
do that in order to keep things in one place.

> 3. What goes into releasing a new series for an Ubuntu release
> (timeline for call for contributors, editing, translators,
> mark-as-done? how does the packaging work)

This is flexible, but in essence the steps are described here:

https://wiki.ubuntu.com/DocumentationTeam/ReleaseSchedule

Obviously that page hasn't been updated for a couple of releases so
the dates are not correct, but the steps are more or less correct.
I'll try and make it release-neutral as part of the process of
updating the wiki documentation.

In terms of the packaging, the standard Gnome packaging tools are used
for ubuntu-docs. As noted above, the package is uploaded to Ubuntu in
the same way as any other Ubuntu package. In order to upload, because
the ubuntu-docs package is in main, an Ubuntu core developer needs to
sponsor the upload or someone with per-package upload rights is needed
(I have them for ubuntu-docs, I think probably Jeremy has upload
rights too).

Matt