Documentation as a Standard Part of an LP Project
kyle.nitzsche at canonical.com
Thu Oct 1 14:42:50 UTC 2009
Hi Milo and all:
It strikes me that there are two aspects to this:
1) establishing a well understood framework for package documentation
2) LP to facilitate this structure and the work that flows from it
These are related but not identical. I think we can go a long way with
1) before 2) is in place.
That is, we can establish working models (best practices) for
documentation in a package that's hosted as an LP project, that's
translated in Rosetta, that installs when the package installs and is
displayed by Yelp when the user presses the package's Help UI button (I
need to look into his bit). This will enable per package documentation,
albeit with a little more tracking/management work until 2) is in place.
We can also pursue 2) LP integration (possibly through the idea of a
"Documentation" Tab). This will serve the important goal of facilitating
Documentation Group and Translation Group activities, for Ubuntu and
More comments below.
Milo Casagrande wrote:
> Hi Kyle,
> 2009/9/30 Kyle Nitzsche <kyle.nitzsche at canonical.com>:
>> Are you going to be at UDS?
> I don't know, yet, if I'll be able to make it.
I very much hope you can make it.
>> If so, perhaps that would be a good chance to discuss/refine/define things
>> as part of the process for getting a good blueprint together.
> Yes, indeed. I would like if possible to start the blueprint before
> the UDS from this discussion, but meeting and discussing in person is
> totally different.
Let's continue to work on this! I will soon set up a wiki we can use to
start noting and refining the ideas.
>> As a starting point, how about:
>> * the basic idea is that a source package may contain its own help (probably
>> packaged in a standard way to facilitate LP integration, translation, etc.)
> Yes, right now there are packages (few of them though) that ship their
> documentation/help in a different directory than usual. That's
> something that should be documented too.
What is the "usual" directory for a package's docs? If there is
something in use now, we should probably propose that to minimize
migration work. Otherwise, I propose documentation/ (how's that for
original and exciting? ;)
I recently did some work on the ubuntu-desktop-course package's build
structure (it's Makefile) for i18n. This is a docbook book. The work I
did enables localized images (screenshots) and streamlines creating pdfs
and html (localized). (There's a known issue with Cyrillic - anyone here
knowledgeable about Cyrillic and dblatex? :)
I wonder whether this structure might serve as a template for a/the
standard/documented format/expectations for the documentation/ directory.
You can check it out here:
Get the branch containing the i18n work as follows:
bzr branch lp:~knitzsche/ubuntu-desktop-course/ubuntu-desktop-course-i18n
Its README file explains key points, including how to localize images
(touched on below as well).
A few notes about this:
* there are subdirectories for each chapter and each of these has a po/
directory that contains the template (the pot) for the *chapter* (The
book xml file is also in a directory, as are supporting xml docs that
aren't "chapters"). Thus, there are multiple templates (pots) for the
book (one per subdirectory). If this structure were used (which seems
like the easiest path at the moment), it would mean multiple translation
templates *just for docs* in the Translations tab. As opposed to having
a single pot and template for the *whole* book or even mixing the book's
template together with the UI template, if any. This seems OK to me but
I am wondering about the usability. Assuming we explain it to the
community properly, is there any issue with this multiple translation
* since this project is already set up for i18n/l10n with gettext (pots
and pos), it should be easy to set it up for integration with launchpad
translations. the LP translation team's recent bzr import and export
features should work without any fuss (they tell me ;-). That is, if
there are*any* pots and pos in *any* directory, they are imported to
Rosetta. if automatic export is set up, pos are created from current
Rosetta and exported to the same directory position they came from.
>> * Each package should/can have a "Help" (or "Documentation") tab in LP
> IMHO, I think "help" could be misleading: people might think of it as
> Launchpad help...
>> * In that tab, one might set the Permissions (Open, Assigned, Closed, ...)
>> * And widgets to assign the package to a Documentation Group (say, "Ubuntu
>> Docs") (much like one now assigns a package's translations to Ubuntu
> Yes, like the management interface for translations: simple and efficient.
>> * Perhaps show some status, for example: "Help is Under Development" (which
>> means feel free to change the source), or "Help is Frozen for String Freeze"
> This would be awesome for translations too! :)
> Maybe even an "automatic" announce when you enter string freeze...
>> * Documentation groups could get an LP page that automatically lists the
>> packages assigned to them (like Ubuntu Translators does, although I can't
>> find that at the moment :)
> This one probably:
> at the end of the page.
>> * Naturally, there would be a documentation group for Ubuntu: Ubuntu
>> Documenters (or something).
>> ( * There might be language specific teams: not for *translation*, but for
>> screen shots ? )
> I think screen shots localization should be done within a translation
> team. There could be an upload interface to upload the screen shots.
> At least right now documentation screens shots have always been done
> by translation teams.
> There should be a preview of the screen shots though: original and
> localized (something like GNOME has).
Naturally, this would require LP development. It seems to me that this
part of it (an LP UI for localizing screen shots) while *very important*
may be a feature that could be delivered later. That is, this is part of
2) above, not 1). And some parts of 2) might be easier than others. In
the meanwhile, it could be done by adding the localized image files to
bzr branches and merging them. The way my i18nized branch of
ubuntu-desktop-course works is that each chapter has a directory and
each of them has an images/ directory: for example chapter1/images. If
you want a localized version of a particular screenshot, you add a new
images directory named after the lang code as follows:
chapter1/images-de. Then, you put a localized image *of the same name as
the one in images/* into it. The localized images are layered on top of
and replace non-localized ones. So it is pretty easy to work with.
>> * would help translations be delivered by the package or in language packs?
>> Well, probably for Ubuntu, lang packs, but for upstream LP packages, by the
>> package itself.
> That's an interesting point. We've been talking a little bit about
> this with the GNOME guys: why should I have the documentation
> translation of an application I don't have installed?
> I know it's the same approach that applications translations use right
> now (you have all .mo files even of applications you don't install),
> but shipping documentation all together takes up more space (screen
> shots, XML file). It's a tricky part...
> So, it's something that need to be discussed.
Yes, discussion needed.Given the potential size of docs, it may be
preferable in the short term to not install them with language packs
(data needed). At any rate, taking that approach in the short term is
likely since it would take time and effort to get them INTO lang packs,
even though that may turn out to be the better approach in the long
term. This approach would mean that if you install an application, you
get ALL its translated docs. So there is disk space over utilization in
>> * Thus, there should be a well-known toolchain to support extraction from
>> source docbook (to start with) to po (xml2po anyone?), upload to LP (import
>> translations from bzr branch?), and, after translation is complete, export
>> to po in bzr branch. These imply a standard structure for help in a package,
>> which may be new, but I don't think is too hard.
> There is also a check in the translate-toolkit  that will perform
> XML tag consistency (it's kind of a basic check and can give false
> positives, but better than nothing). Could be interesting to integrate
> also that one into the toolchain, like a daily-hook that will check
> consistency, maybe only during string freeze, if it's not possible to
> do it on a per-page basis when you save your translation.
xmllint to validate xml?
>  http://translate.sourceforge.net/wiki/toolkit/index
More information about the ubuntu-doc