Documentation as a Standard Part of an LP Project

[Kyle Nitzsche]

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 generally.

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: 
https://code.edge.launchpad.net/ubuntu-desktop-course.
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 
template structure?
 * 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...
>   
+1
>   
>> * 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
>> Translators)
>>     
>
> Yes, like the management interface for translations: simple and efficient.
>
>   
+1
>> * 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"
>> etc.
>>     
>
> This would be awesome for translations too! :)
> Maybe even an "automatic" announce when you enter string freeze...
>
>   
+1
>> * 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:
>
> https://translations.launchpad.net/+groups/ubuntu-translators
>
> at the end of the page.
>   
right.
>   
>> * 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.
>> Questions/thoughts:
>> * 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 
either case...
>   
>> * 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 [1] 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?
> Ciao.
>
> [1] http://translate.sourceforge.net/wiki/toolkit/index
>
>   

Cheers,
Kyle