Software Store Help

[Kyle Nitzsche]

Hi,

There are other downstream releases of Ubuntu (for example the Canonical 
OEM group's UNR releases) that sometimes do not display the Ubuntu Help 
Center at the client's request because the content *as a whole* is an 
imperfect fit for the slightly modified systems. This is a loss because 
most of the help is relevant, and this help probably is be too.

(Someday soon (Gnome 3), maybe Gnome's Mallard and its "pluggable" doc 
framework will come to the rescue.)

For now, including *all* help in a single package whose content is 
displayed monolithically by default makes it difficult to customize the 
help that is displayed in Ubuntu permutations. In practice, it amounts 
to an "all or nothing" approach to Ubuntu Help Center content, which 
has, in some cases, and because of the challenge to customize it, meant 
"nothing".

Therefore, I think that thought should be given to migrating Ubuntu docs 
processes and work flow to fit the evolving (and more complicated) 
Ubuntu ecosystem. Which may mean handling separate packages too.

In the mean time, I propose this app's help content should be kept 
separate and should be launched from within the package, to ensure it is 
actually present on all systems.

Cheers,
Kyle




Matthew East wrote:
> 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.
>
>