Documentation as a Standard Part of an LP Project

[Milo Casagrande]

Hi Kyle,

2009/10/1 Kyle Nitzsche <kyle.nitzsche at canonical.com>:
> 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,

Hmmm... we need also to clearly define the translation part since with
a project it's associated say "one" translation, the UI one... I
really don't know if it's possible to set up another translation for
the same version of that project. We really need to check.

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

Yes, that will need also a "doc-person" in the project that step up
and take care of this aspect, since as long as 2) is not in place,
lots of work has to be carried out "offline". Oh.. and project should
really start defining a time-scheduled release :)

A good wiki page will be mandatory.

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

> Let's continue to work on this! I will  soon set up a wiki we can use to
> start noting and refining the ideas.

That would be great and really appreciated! Thanks!


> 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?
> ;)

Well... actually I was thinking about GNOME apps... they usually have
a help/ directory, plus the beloved C/ as the "working" directory. All
other directories under help/ are for localization purpose. Maybe we
can mimic the same structure for other projects too, event not
application. Even this is something we might sit down and think of,
maybe with some experience from the desktop course...

> I wonder whether this structure might serve as a template for a/the
> standard/documented format/expectations for the documentation/ directory.

I think this will be definitely useful.

> 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?

Well... if we go with one template, there will be a really *huge*
template to translate, pros and cons to this approach as usual, but I
think that different templates for different parts of the course
(chapters in this case) might be OK (w are talking about the course
here, maybe another project could use a different approach). Different
translators could work on a different part speeding up the translation
process.

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

Exactly. But you still need to convert them to XML or PDF or whatever...

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

Absolutely agree with that. This is something that a new member of the
Italian team asked: "How can I send localized screen shots?". He was
looking for some Launchpad interface actually. But for the time being,
I totally agree with you.

> Yes, discussion needed.

I think we need to discuss it even with packagers...

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

Yes, indeed. As a starter

> xmllint to validate xml?

Yes, that's for validating a real XML file. What i was referring to is
a check on a PO file to test if XML tags have been written correctly.
xmllint can't do that and we need a check directly on the PO to ensure
that after translations have been sorted out, the final XML is valid,
but before creating it. I mean, we can even do the check on the final
XML file (as Matt does now I think), but that's something that Ubuntu
can do, manually, but we cannot rely on it since it's a hard task that
maybe not all project maintainer are willing to do.

Ciao.

-- 
Milo Casagrande <milo at casagrande.name>