Re: Successor to DocBook

[Don Scorgie <DonScorgie Blueyonder co uk>]

On Mon, 2006-07-10 at 11:41 +0100, Matthew East wrote:
<snip>
> 
> 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 think there are a couple of issues with docbook:

* It tries to offer too many things.  Have a look into the Yelp /
gnome-doc-utils bug reports (esp. the closed as WONTFIX ones).  There
are loads of them with "You probably don't want to use this docbook
element.  Instead use this one, its correct here." type answers.  There
should only be 1 type of link (for example), instead of $NUMBER that
docbook offers, each one slightly different and for a different purpose.

* Docbook is very much aimed at book structures - a series of chapters
or sections to be read linearly.  Help shouldn't be this way.  It should
be topic based (Mallard's main principle).  See Shaun's original blog
entry on Mallard.

* There is no way to dynamically alter docbook docs based on what other
docs are on the system.  E.g. if one (say) IRC client is included, it
should have a mention in the Desktop guide.  If another is installed
instead, the Desktop guide should now link instead to this new document.
(I haven't explained this well, but in my mind it makes sense)

* Learning docbook is pretty hard going.  Even the subset GNOME
recommends is still pretty hard going to follow it all.  This raises the
bar to entry.


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

Hopefully the resulting format will be similar enough to a subset of
docbook that these tools should be easily altered to produce good
output.

Don