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

[Kyle Nitzsche]

Just to be clear, I am asking whether the idea of dropping the "ugly 
hack" Ubuntu Help Center and moving to a model of Gnome help + Ubuntu 
topics has been thoroughly analyzed, discussed, etc. This would be a 
large change that warrants serious consideration and intentional, 
deliberate moves. I have no particular opinion whether it is the right 
thing to do. I have some doubts, which might certainly turn out to be 
non-issues.

If  this is the strategic direction, clearly the argument for moving all 
system docs to Mallard is stronger. If not, weaker.

Again, just trying to work out what the strategic goals and direction 
are without a pre-determined opinion. If we don't know the strategic 
goals, it's harder to evaluate options.

Few comments below.

Matthew East wrote:
> 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.
>   
I think re-use of all relevant gnome upstream docs is critically important.
> 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.
>   
Not sure I agree 100%. I think system docs should be decoupled into 
multiple packages to facilitate customization, position nimbly for 
growth, and enable different build systems as appropriate to the use 
case. Some build systems make it harder to localize images than others. 
As you know, I assert doctemplate makes it as easy as possible to build 
localized docbook  (with images), so it makes sense to consider using it 
for the New to Ubuntu topic (since images are so particularly compelling 
in this use case and justify the extra work, which should be done by 
docs people, I think, not translators given LP's current non-support).
> 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.
>   
Actually, I never argued for a rigid set of requirements. I'll paste in 
my relevant text from the email here:

"Without a working set of published, high-level requirements, it is 
difficult to evaluate proposed changes, such as a transition to mallard. 
Or plan and prioritize new work, identify shortcomings, etc. I do *not* 
think requirements should be excessively detailed or lengthy. Nor can 
they ever be fully correct. And they must change with circumstances (for 
which there should be some public process with public input). But 
without this, there is no consensus "true north" by which decisions can 
be made by all concerned.

Perhaps most importantly, a working set of requirements facilitates a 
community in which people believe their input is evaluated against some 
objective criteria, which makes for a healthy and expressive community.

I propose that if such high-level requirements do not exist, we forms 
plans to bring them into existence, along with a process for modifying them.
"

I now think the term "strategic goals" is a better fit than "requirements".

Cheers,
Kyle


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