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

Matthew East mdke at ubuntu.com
Wed Jan 27 19:33:05 UTC 2010


On Wed, Jan 27, 2010 at 5:22 PM, Kyle Nitzsche
<kyle.nitzsche at canonical.com> wrote:
> 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.

I'd like to refer to what you're talking about as "considerations".
Whenever one takes a decision on something, one takes into account
different factors that might or might not be relevant in each case.
Those factors, or considerations, will be of different importance or
relevance depending on what sort of decision one is taking. Sometimes
they will be very relevant, and sometimes they will be less relevant.
Sometimes they won't be relevant at all, in which case they are not
even considerations. One has to weigh all the relevant considerations
up.

To relate that to this discussion by giving some examples that have
been discussed recently, I would say that the ability to integrate our
material closely with upstream material is a relevant consideration to
the decision of whether to adopt Mallard or not, because it might be
easier to do it with Mallard than without it. The weight of that
consideration is debatable, because I think that it's important, and
you don't.

On the other hand, whether we want the ability to use localised
screenshots is not a consideration for the purposes of this particular
decision because one can do this regardless of the markup used. It's
just another separate question, which has its own considerations and
discussion to arise out of that.

Broadly, I agree with you that we need to know what we want. But we
also need to make sure that we are relating relevant considerations to
the particular decision under discussion. So I'm comfortable with the
approach which I think was broadly agreed during the meeting on this
which was (a) to seek to improve our wiki pages to set out broadly
what our aims are in terms of providing helpful help to users, and
ideally to incorporate the same in our style guide; and (b) to prepare
a spec on Mallard transition that deals with the relevant
considerations both for and against. A rigid list of "requirements"
which govern all decisions taken by the team doesn't seem to me to
match the sort of common sense and flexibility that one needs to show
when discussing decisions like this.

> So I wonder, what is the status of this particular strategic direction?
> * Has the decision been taken?

No, as I said, the bit that you quoted reflects my opinion about this
issue. Until you disagreed with it, I thought that it was
uncontroversial and a matter of straightforward common sense, but
maybe I was wrong about that.

> * 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?

These are things that we are discussing on this thread, I suppose.

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

If it transpires that the upstream documentation is totally
inapplicable to Ubuntu and cannot be reused, then obviously we are
going to have to think about how we handle that. I personally think
that it is very, very unlikely, unless Ubuntu decides not to reuse
much upstream code either. *One* of the goals of Gnome documentation
(IMO) should be to provide a common denominator base of material which
distributions can add to in order to provide coherent and complete
user help, and as long as they do that, then I think it will be worth
reusing their material.

Ubuntu as a product is based on the concept of standing on the
shoulders of giants, and I don't think you've made a case for not
adopting this concept with help. Just as we use version control and
patch systems to track divergences from upstream code, so we can use
the same techniques to track divergences in upstream documentation.
But the reality I think is that Ubuntu adds to Gnome a lot more than
it modifies it, hence my opinion that the pluggability that Mallard
would give us is likely to be quite key when we weigh up the
considerations.

> The difference in the
> user experiences between Gnome and Ubuntu is likely to increase, not
> decrease.

I don't know on what you base that opinion, but I disagree. I actually
think that collaborating and giving back to upstream is as important
to Ubuntu as a project as it ever was, and probably more so.
Unnecessary divergence from upstream will continue to be kept to a
minimum and I know that when Ubuntu develops new technologies there is
an effort to merge them back upstream. But even if divergence does
increase, I still think that there is a lot of value in reusing
material from upstream where possible.

> And, as mentioned below, Mallard allows adding topics, not
> removing them.

As I said above, I think that adding topics will probably be the key
part of our work because I think that Ubuntu adds a lot more to Gnome
than it modifies. But what Mallard allows is more than that. It
provides us with the ability to *integrate* material with that
provided by upstream. Without that ability, we either have to adopt
the ugly hacks that we use now (see for example the way that we link
to the Gnome user guide in various places) or simply rewrite material
from scratch that is covered upstream.

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




More information about the ubuntu-doc mailing list