Transition to Mallard?

[Phil Bull]

Hi Thomas,

On Thu, 2010-01-21 at 15:50 -0600, Thomas R. Jones wrote:
> > What interests us here is not to allow authors to produce more
> > documentation. It's to produce documentation that is more helpful for
> > our users.
> No. You are back tracking now. You stated that docbook was too complex  
> and authors do not need to learn it. You implied that Mallard with  
> it's watered down XML is easier to author. You are simply totally one  
> hundred percent incorrect. I would appreciate it if you would stay on  
> topic.

I used to run the Docteam mentoring scheme. A lot of newcomers had
problems getting used to DocBook, and I invested a lot of time in
teaching people the same things again and again. I've never particularly
liked authoring DocBook because I always find that a lot of boilerplate
is required, that there are many ways of doing the same thing, and that
the tags have long names (I'm sick of typing <menuchoice><guimenuitem>
every four lines). These confuse newcomers and hinder me.

We don't need the full power of DocBook. We only ever use a very small
subset of tags. We don't want to spend all day writing long tag names
and nesting content to five levels. We want standalone pages that don't
need a bunch of esoteric XML commands in order to get them into a useful
structure. I imagine that we could hammer DocBook into this shape, but
who is going to do the work? It's not easy stuff. Open source projects
are susceptible to losing people with specialist skills like the ones
required to do this.

At the end of the day, I think that heavily modifying DocBook would be
like fitting a square peg into a round hole. DocBook is very good for
linear, book-type manuals. It's not very good for topic-based stuff.

> > It's absolutely clear that topic based help is easier for users to
> > understand when dealing with on-screen help. It's not controversial
> > and I can't see the Ubuntu doc project or the Gnome project changing
> > their minds about that.
> Wow. And how do you come to this conclusion? In fact, I will post  
> later specific documents that in fact prove that you are incorrect.  
> Truth be told, a taxonomy-based approach has always been proven to  
> provide better results. The crutch with this approach is the  
> complexity and vast amount of information presented. Don't believe  
> me.....go to your nearest university and inquire.

Please justify this. It contradicts a lot of what I've read about user
assistance best practises.

Thanks,

Phil

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