Transition to Mallard?

[Phil Bull]

Hi Kyle,

Thanks to you and Thomas for your comments, they're really constructive.
This is the sort of discussion we should be having before making a leap
like this.

On Wed, 2010-01-20 at 16:18 -0500, Kyle Nitzsche wrote:
> Regarding some of the the advantages put forward previously for Mallard:
>  * simpler syntax: docbook isn't that hard for writers. If you can't 
> deal with it, should you really be writing docs?

I've been writing DocBook for about five years now, and I've never found
it very intuitive. True, it's not that difficult once you know what
you're doing, but it can suck all of the fun out of writing. For our
purposes, I feel that it's overengineered. This is a pretty subjective
argument, though. Try Mallard for yourself for a while and see what you
think.

>  * highly modular & topic based: there's nothing in docbook that 
> prevents or discourages modular and topic based writing. See the 
> xinclude examples thoughtfully included below and consider the fact that 
> a <section> can contain a <section>: 
> http://www.docbook.org/tdg/en/html/section.html

DocBook was designed with book-type manuals in mind. You have to put
everything in an article or chapter, which is then split up into
sections. This forces us to linearise topic-based docs, rather than
putting each topic in a file and then organising around that. Hence DITA
and Mallard. I'm sure you could go through some contortions to get
DocBook working in the same way, but why?

>  * topics self-link to the main page reducing maintenance. Very nice, 
> but how important really? If it's a part of ubuntu-docs, put it on the 
> index page. Otherwise, let it be freestanding. Do we really want help 
> for random application X linking itself to the main help page? Can this 
> even be prevented if that's desired? Why do people think this is such a 
> compelling feature?

It's nice because you don't get broken links and you don't have to keep
track of the relations between documents yourself. If I modify a
subtopic in DocBook, I also have to update any pages that link to it. If
you're changing out a page, this can make for quite a substantial, messy
patch. This makes restructuring the help much easier, and structure is
definitely something we need to be looking at more.

I don't think that random apps linking in can be prevented at the
moment, but packagers shouldn't allow that anyway (the docs would have
to go into the same directory). The nice thing is, we can request this
feature if we want it.

>  * well-supported upstream. *only*. Note the list of docbook standards 
> below.

It's supported by our biggest upstream, who we talk to a lot. When do we
talk to the DocBook upstream guys?

>  * better navigation: docbook doesn't impose doc navigation limits that 
> I know of. It's the way it is deployed that determines navigability. 
> Consider that my thrown together web page is a docbook article that I 
> converted to html by running 'make_html': 
> http://people.canonical.com/~knitzsche/

That's true. We could probably modify our DocBook stylesheets to get
similar navigation working.

>  * it's a new feature, which people like: end users don't care about new 
> features. When they want info, it's to solve a problem they are having.

I was being a little flippant when I included that point... No matter,
because new features get us publicity, which is something that we could
do with.

> My 2 cents: use  docbook (the "giant among men") better instead of  
> switching to something brand new and shiny too soon. Better to give it a 
> chance to mature and shake out its kinks. Then proceed *deliberately*.

Using DocBook better will take a lot of effort, and we'll probably
switch to Mallard soon anyway, to keep compatibility with GNOME. I'd
rather invest the time in working up Mallard support. I take the point
of stability, though. There are some document that we can watch (like
Empathy's help) to evaluate problems with Mallard.

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull