usb-creator Draft

[Matthew East]

Hi Phil,

On Tue, Aug 11, 2009 at 9:24 PM, Phil Bull<philbull at gmail.com> wrote:
> On Tue, 2009-08-11 at 18:47 +0100, Matthew East wrote:
>> Where there is an active upstream documentation project, you're quite
>> right, and several contributors to ubuntu-docs (most notable Phil and
>> Milo) are also contributing actively with Gnome upstream. Equally,
>> where material is suitable for use upstream, we don't hesitate to pass
>> that on. However, usb-creator is a native Ubuntu project: it doesn't
>> have an upstream to speak of and as a result I believe that the result
>> of including this documentation in the usb-creator source package
>> rather than directly in ubuntu-docs would be:
>>
>> (a) it wouldn't be updated properly as there is no "upstream
>> documentation team" and the ubuntu-docs team doesn't have direct
>> access to the relevant bzr branch;
>
> This is an easy fix. We can just send merge proposals from an
> ubuntu-core-doc branch. I'm sure the branch maintainers will be happy
> that someone else is dealing with the docs and will merge the branches
> in a timely manner.

Yes, it could be done like that, but it's an extra step for what seems
to me to be no obvious win. If we start separate branches for such
projects, it will be more effort to track them and to ensure that they
are getting updated regularly. It will become more cumbersome to track
bugs on the individual packages rather than just tracking ubuntu-docs
bugs, and translations will be a nightmare (see below). This isn't
working much for the other package that we are doing it for
(gnome-user-docs), which isn't getting any serious attention from the
team. I really do think it would be much simpler to ship the material
in one branch, which has worked very well for the jockey docs.

>> (b) it wouldn't be translated at all because translating xml is
>> difficult, requires manual work and setting up a special toolchain
>> which ubuntu-docs already has in place.
>
> The same as above... can't we just push the translations to the main
> branch from our own branch? Or, maybe we can convince someone to add
> proper XML translation support to Rosetta? That would be a major win for
> the open-source documentation community, I think.

Rosetta already supports translation of any format which can be
converted into po files with gettext. I think what you're suggesting
is to add XML translation support to the langpacks so that the
translations can be exported automatically from Rosetta and imported
into Ubuntu. The problem is that the tools for converting XML to po
files themselves are relatively weak, they don't work in the same
simple way that translation of software works. The result is that we
need to download translations from Rosetta manually and correct any
XML validity errors that abound as a result of translator errors, then
convert the po files to XML during or prior to the package build. This
is quite a time consuming process, and although we've discussed
improving it with the Rosetta developers (one of whom also wrote the
xml2po utility that we use), improvements to it are no more than a
pipe dream at the moment and would require a serious amount of effort
from someone who is an expert in all of these tools.

The upshot of all of this is that preparing, exporting and importing
translations for ubuntu-docs is a serious effort, and trying to do it
for several packages is impractical. At the moment we are doing it for
the various ubuntu-docs flavours and gnome-user-docs and it's a heavy
burden. If we were to start doing this for jockey, usb-creator,
gnome-app-install and other native Ubuntu applications (all of which
use the regular langpacks for their software translations), it would
become beyond our capacity.

Obviously that would change if we can get langpack support for XML
translations, but I'm not counting the minutes for that to happen.

>> This is very ably demonstrated by the documentation for
>> gnome-app-install, another native Ubuntu application, which was
>> written by Jerome in 2006. It hasn't been updated since 2006 and is
>> only translated into one language (Swedish). Compare that with the
>> actively maintained ubuntu-docs branch which is translated into tens
>> and tens of languages.
>
> Yes, I'd always wondered about that. I think that we should take over
> the maintenance of all of the Ubuntu-native documentation, but keep the
> docs with their respective packages. This makes sense from a packaging
> perspective (having a dep on ubuntu-docs is restrictive), and will also
> allow code to be used by non-Ubuntu projects more easily (e.g. jockey).

I don't think a dependency on ubuntu-docs is at all restrictive
really. If a project is genuinely a native Ubuntu application, then a
dependency on ubuntu-docs (which is seeded in the default Ubuntu
install) is not unreasonable. If a project becomes something that
might turn into an upstream project, I don't think it will be
difficult to adapt and adopt the documentation accordingly.

> I think that this would make it easier for people to work with the doc
> team, too. I'm concerned that other teams don't currently come to us
> when they need docs doing.

I can see where you are coming from there but I think that's something
we can address on another level, i.e. by promoting the image of the
documentation team in the community and offering to help with
documentation for new initiatives. Perhaps we can include this
information as part of the developer documentation.

-- 
Matthew East
http://www.mdke.org
gnupg pub 1024D/0E6B06FF