Software Store Help

[Matthew East]

Hi Matthew,

On Tue, Sep 22, 2009 at 12:10 PM, Matthew Paul Thomas <mpt at canonical.com> wrote:
> I'm sorry I don't know much about this issue, so I have more questions
> than answers here.

That's ok, I don't have the answers to all of your questions, but I'll
do my best.

> How long has translation of help files outside of ubuntu-docs been a
> problem?

As far as I know, always.

> What is the plan for automating the po-to-XML process so that it can be
> used consistently across other packages?

I'm not aware of any plan. There is a section in this spec which deals
with it (https://wiki.ubuntu.com/DesktopTeam/Specs/JauntyGnomeHelpLangpacks)
- the section entitled "Long-term solution" but I don't think anyone
is working on it.

> If there is no plan for this, is it the position of the Ubuntu
> Documentation Team that the help pages for every application in Ubuntu
> should be part of the ubuntu-docs package?

The team doesn't have an official position, although we have discussed
the issue in relation to usb-creator here:
https://lists.ubuntu.com/archives/ubuntu-doc/2009-August/013508.html

I certainly wouldn't suggest that the help pages for every application
in Ubuntu should be part of the ubuntu-docs package. Upstream projects
maintain their own documentation, and maintain the translations for
that documentation as well (e.g. gnome-user-docs). However, for
projects which are Ubuntu-only (like jockey and usb-creator), I think
there are definite advantages with shipping the documentation in the
ubuntu-docs package.

> If the Ubuntu Software Store help was part of ubuntu-docs, and someone
> uninstalled the Store and installed Add/Remove instead, would the
> visible help pages change to reflect this? If so, how would that work?

No, we don't have the technology to do that. This could of course be
subject to discussion, but personally I wouldn't bother documenting
Add/Remove in our documentation if it is not installed by default and
software-store is. I think that the use case you've described would be
marginal enough to ignore it. The alternative is to refer to
Add/Remove in the same document as an alternative method of package
management, but I think that (unlike Synaptic or command line tools)
it doesn't have enough compelling alternative features for most users
to be interested in it.

> If someone was developing a branch that changed the interface of the
> Store, so they needed to update the help to match, how would they do
> this? Would they need two separate branches, one for software-store and
> one for ubuntu-docs? If so, would Michael Vogt have write access to the
> ubuntu-docs trunk, so that he could land the two branches simultaneously?

Usually when an application changes in Ubuntu that affects the help,
the docteam updates the help accordngly. If the change occurs during a
freeze, the freeze rules normally require the docteam to be informed
so that they can make the change. Although Michael wouldn't have
access to the branch (unless of course he joined the Ubuntu
Documentation Committers team via the process described here -
https://wiki.ubuntu.com/DocumentationTeam/Organization) he could
certainly submit merge proposals or patches which would be reviewed.

As matters are now, it's the other way around (ie the docteam would
need to submit merge proposals or patches) and I tend to think that's
the wrong way around because the idea is that the docteam specialises
in documentation and developers specialise in code. But having said
that, for me the translation point is much more persuasive than the
docteam workflow point.

> Does Debian use the ubuntu-docs package at all? If Debian adopted the
> Software Store for their own repositories, would the help pages need to
> move back inside the Store codebase?

No to the first question. As for the second question, the help pages
would need to move either into the store codebase, or a separate
package. This is why if a program were to be considered an "upstream"
program, then my opinion would change and I'd say that the upstream
project should take care of documentation and translation.

>> One point that would need addressing is the license. Currently it's
>> GNU/FDL, and it should ideally move to cc-by-sa 3.0 which is the
>> ubuntu-doc team's preferred license, and the license of the
>> ubuntu-docs package. It's also the Ubuntu project's preferred license
>> for non-code. That would require the consent of the three individuals
>> who have contributed to the document, if existing content is to be
>> merged with the ubuntu-docs package.
>>...
>
> Weird, I didn't know the Store help was licensed under the FDL.

I may have got that wrong, but that's what I read when I had a look at
the document.

> It
> should be using the GPLv3 instead, same as the rest of the code --
> because it is quite likely in future versions that some of the help will
> be embedded in the code, and vice versa. This wouldn't be possible with
> the CC-BY-SA either, as far as I know.

I think this would probably be a fatal objection to putting the
document in the ubuntu-docs package, unless a workaround is found for
that or new material is written when/if this happens.

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