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

[Matthew East]

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. 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.

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.

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