Re: Successor to DocBook

[Shaun McCance <shaunm gnome org>]

On Mon, 2006-07-10 at 14:13 -0400, David Malcolm wrote:
> On Mon, 2006-07-10 at 12:04 -0500, Shaun McCance wrote:
> > On Mon, 2006-07-10 at 11:41 +0100, Matthew East wrote:
> > > * Don Scorgie:
> > > > (Resend.  Hopefully it'll go through this time)
> > > >
> > > > On Fri, 2006-07-07 at 13:45 -0500, Shaun McCance wrote:
> > > >> On Fri, 2006-07-07 at 14:19 +0200, karderio wrote:
> > > > <snip>
> > > >> Now here's everybody's first chance to get in on the fun:
> > > >> The code name for the project-as-a-whole is Project Mallard.
> > > >> This is sort of an inside poke at DocBook.  But Mallard is
> > > >> a dumb name for a help format.  So everybody:
> > > >>
> > > >> NAME MY XML FORMAT!
> > > 
> > > I am really happy that lots of thought and action seems to be happening
> > > in relation to improving the structure of the help system and making it
> > > easier to have upstream and distro documentation sitting alongside each
> > > other.
> > > 
> > > However, if I might add a word of caution. I have not seen anything in
> > > the recent threads which documents *why* a move away from docbook is
> > > actually necessary for a better help system to work.
> > > 
> > > I haven't seen any discussion of it either.
> > > 
> > > I have to say, that with all the progress that has been made on the
> > > toolset around docbook [1], a sudden move away from docbook just feels
> > > slightly like moving the goalposts.
> > > 
> > > [1] Especially the fact that we will soon have tools available to allow
> > > people to work on a WYSIWYG basis in a collaborative way (via a Moin
> > > wiki) and produce docbook.
> > > 
> > > This isn't really a criticism, but I'd really like to know why docbook
> > > has been rejected as inadequate for the implementation of a modular help
> > > system. I'm not attached to a particular format as such, but I think
> > > that now that some good work has been put in to supporting docbook, I'd
> > > like to see a move away from it justified more carefully.
> > 
> > It's not really so sudden.  The idea of replacing DocBook has been
> > floating around for years now.  Discussions have happened in lots
> > of places, including IRC.  (Sidebar: somebody please create an IRC
> > client that doesn't suck.  Allow me to select a range of discussion
> > and send it to a mailing list for public consumption and archival
> > with no more than three clicks.)
> > 
> > The original manifesto for Mallard is dated 2005-10-01:
> > 
> > http://www.gnome.org/~shaunm/quack/mallard.xml
> > 
> > That was only the first coherent article, though.  Discussions and
> > ideas had been going around well before I wrote that.  Do read it.
> > It will provide some answers to your questions.
> > 
> > DocBook is inherently linear.  Doing anything non-linear with it
> > is a royal pain.  We want standalone pages, each interlinked into
> > one or more navigational pages.  We could hackishly provide this
> > with DocBook and a huge pile of processing instructions, but then
> > our DocBook isn't really DocBook anymore.  Plus, writers would be
> > burdened with trying to keep a structure in their head that isn't
> > really reflected in the format they're dealing with.
> 
> BTW, have you looked at DITA?  It appears to be designed more around
> collections of short articles on topics, rather than humongous top-down
> sections, with subsections ad inifitum:
> http://xml.coverpages.org/dita.html
> http://www-128.ibm.com/developerworks/xml/library/x-dita3/#N257

I have looked at DITA.  It looked somewhat promising at first,
but we have a fundamental difference in design philosophy.  My
design philosophy is "as simple as possible, and no simpler."
This could also be restated as "make life easier for everybody
involved."

The DITA folks are trying to make an all-singing, all-dancing,
eclectic, mangleable, transwackificatable, meta-meta format.
They want people to extend DITA.  I just want people to write
good documentation.

More concretely, the DITA folks have put a lot of thought and
effort into making a *complete* architecture for information
mapping.  Like RDF, it is impressively capable of just about
anything you want to express.  And like RDF, it's just not
fun to deal with by hand.

On the flip side, I've put a lot of thought into how I can
get 80% of our information mapping needs with very minimal
effort from documentation people.  Hierarchical document
structures are easy to keep in your head, but they don't
satisfy our needs.  My goal is to replace hierarchies with
a paradigm that's equally easy to keep in your brain, or
at least as near as possible.

--
Shaun