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 _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
