Questioning assumption that since gnome > mallard, so *must* ubuntu docs

[Kyle Nitzsche]

Matthew East wrote:
> On Tue, Jan 26, 2010 at 10:07 AM, Kyle Nitzsche
> <kyle.nitzsche at canonical.com> wrote:
>   
>> My question really is: why is it a "slam dunk" that since gnome 3.0 is
>> moving to mallard, ubuntu-docs is too, albeit at some point. (That's a
>> quote from the meeting log:
>> https://wiki.ubuntu.com/MeetingLogs/DocTeam/January2010)
>>
>> We've established that docbook content can include mallard, so ubuntu
>> docs could theoretically remain docbook and include new gnome mallard docs.
>>
>> I am explicitly questioning this assumption because I don't understand
>> it yet. So what's the reasoning here?
>>     
>
> I was the person who you've quoted there so I'll explain what I mean.
> It isn't an assumption so much as an opinion.
>
> (Incidentally, it might be better to have Mallard related discussion
> on a single thread rather than raising each new question/point on a
> separate thread. That way the discussion is easy to find when one is
> going back over things.)
>
> With the introduction of Mallard, Gnome plans to rewrite its user
> documentation. Given that Ubuntu uses Gnome as its desktop, we should
> strive to reuse as much user documentation as possible in order to
> avoid reinventing the wheel and duplicating material. That's what we
> do with our software, and documentation is not different. 
Hi Matthew and all:
 
This ^^^ is what I consider a "Strategic Requirement" or goal, or 
whatever you'd like to call it. Namely, this is a high-level direction 
that informs all other decisions and comes with a large set of benefits, 
costs, capabilities, and limitations. That's really the kind of 
information I was attempting to elicit in the other thread's discussion 
about a need to articulate high level Ubuntu Help Center requirements.

So I wonder, what is the status of this particular strategic direction?
 * Has the decision been taken?
 * Are there articulated rationales, risks, plans, etc?
 * Is there an assumption that this is the right path, or has the 
assumption been analyzed, tested and vetted?

I, personally, am not convinced that the default assumption for other 
upstream software (use it, and customize it as needed) necessarily 
applies to help. The Ubuntu user experience and needs for communication 
may be different enough that it is not the appropriate model. The 
difference in the user experiences between Gnome and Ubuntu is likely to 
increase, not decrease. And, as mentioned below, Mallard allows adding 
topics, not removing them.

At any rate, it's certainly a matter of first-level importance, so 
information about the thinking/planning would be especially useful.

> Proper reuse
> of that documentation doesn't mean just inserting single documents
> into the help system. It means inserting material into the structure
> provided by Gnome, by adopting and using the pluggability that Mallard
> will provide us with.
>   
Mallard allows adding content, not removing it. So refactoring Gnome 
help content would probably be needed.


> At the moment the structure of our desktop help is an ugly hack which
> we have created for our own purposes. Once upstream moves towards a
> similar structure themselves, it seems to me essential that we plug
> material into that structure, rather than maintaining the hack that we
> use now.
>
> The fact that docbook and mallard documents can co-exist within yelp
> is rather obvious: since the inception of Mallard several years ago it
> has *never* been planned to drop docbook support from yelp. However
> the introduction of Mallard should provide us with many advantages,
> the foremost of which is the ability to plug material into upstream's
> work: that's exactly why it was designed, for distributors of Gnome
> like us. And if we want to be part of that we're going to need to
> embrace it, at some stage.
>
> Personally the only compelling counter-argument to adoption of Mallard
> that I can see for our team is the fact that KDE hasn't yet planned to
> move to it. On that basis there is a risk that people interested in
> contributing to both sets of documents might need to learn two
> markups, which is obviously unattractive. However I'm hoping for some
> KDE adoption and I know that Shaun and the KDE guys will be discussing
> this possibility over the coming months, which I feel is very
> important.
>
>