Software Center documentation

Kyle Nitzsche kyle.nitzsche at canonical.com
Fri Mar 5 16:21:56 UTC 2010


Hi all:

Perhaps it's stating the obvious, but it may be worth noting that if 
(when) Mallard arrives in ubuntu-docs it will enable the following:
 * an application can have its help separately packaged (not in 
ubuntu-docs) and delivered (whether through lang packs or not is irrelevant)
 * it can add a link to the appropriate Ubuntu Help Center guide page to 
itself: the user click the link in UHC, and they are taken to the 
localized content
 * its source format can be docbook, mallard, html...

Note that these ^^^ statements make *no* implication for who manages and 
develops the help content or does translations.

This is nice because it enables help topics to be decoupled from a 
monolithic package, which has the following significant benefits:
 * Ubuntu variants can install required help content when Ubuntu Help 
Center is not installed
 * When Ubuntu Help Center is installed, the link to the help content is 
present and indistinguishable (from the user point of view) from links 
to topics delivered by the ubuntu-docs pkg itself (this is perhaps the 
great feature of Mallard - in addition to its simpler syntax of course : )
 * Dividing help into multiple packages enables flexibility on many 
dimensions (build systems, source format, remixing etc.) and positions 
help more nimbly for growth and change

Without Mallard Guide pages in Ubuntu Help Center, one needs to modify 
ubuntu-docs to *add a link* to any separately packaged help content.

Cheers,
Kyle



Matthew Paul Thomas wrote:
> On Mar 5, 2010, at 8:17 AM, Matthew East wrote:
>   
>> ...
>> 2010/3/4 David Planella <david.planella at ubuntu.com>:
>>     
>>> Currently Software Center ships its own documentation, and after a
>>> discussion in the Ubuntu Translations Coordinators team [1] we agreed
>>> that it would be best for documentation and translations to be 
>>> included in ubuntu-docs.
>>>       
>
> Help me understand the reasons given in that discussion:
>
>   
>>       * Translations would be more visible to translators, as they'd be
>>         in the Ubuntu templates list at translations.lp.net/ubuntu
>>     
>
> Why wouldn't the software-center templates be in the templates list at 
> translations.launchpad.net/ubuntu? Does this mean the rest of 
> software-center is currently untranslatable? If so, how should we fix 
> that?
>
>   
>>       * They'd be shipped as part of ubuntu-docs, and integrated in the
>>         package's workflow (i.e. translations would be built before
>>         NonLanguagePackDeadline)
>>     
>
> Why wouldn't translations for software-center help pages be built at 
> the same time as translations for the rest of software-center?
>
>   
>>       * This will make it possible to ship only the translations in the
>>         user's locale (as opposed to all translations). Now ubuntu-docs
>>         are part of language packs.
>>     
>
> Is ubuntu-docs the only package covered by language packs? If any other 
> packages are covered, how does that work?
>
>   
>>       * It would be consistent with what other Ubuntu applications do
>>         at the moment with documentation (e.g. usb-creator)
>>     
>
> Does that mean if you uninstall usb-creator, help pages remain on your 
> computer discussing it as if it's still there?
>
>   
>> I agree that from a translations and documentation team point of view,
>> this would be better, for the reasons which you have listed.
>>
>> However, I proposed this last September and one of the objections was
>> that the help file is licensed under the GPL. If that can change, then
>> I think this would be a good idea. Here is a link to the discussion.
>>
>> https://lists.ubuntu.com/archives/ubuntu-doc/2009-September/013655.html
>>     
>
> As I said in that discussion, the reason for the GPL is that "it is 
> quite likely in future versions that some of the help will be embedded 
> in the code, and vice versa". I hope the same becomes true for the help 
> in every Ubuntu application, because that seems like the primary way to 
> get people to read it.
>
>   
>> There is one other point which I would raise though: as I understand
>> it, Software Center is something of an upstream project, because it is
>> used in distributions like Debian. If that's the case, then there is a
>> clear argument for having help as part of the application which can be
>> used by Debian.
>>     
>
> Yes, here it is in Debian:
> https://launchpad.net/debian/+source/software-center
>
>   
>> Obviously the absence of translations for this help file is extremely
>> unfortunate. And if the decision is taken to keep it in the upstream
>> product, I would say that some serious effort should be put into
>> making it translatable in the same way as the application's interface
>> is.
>> ...
>>     
>
> What else do we need to do to make it translatable?
>
> Thanks
>   





More information about the ubuntu-doc mailing list