-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 Shaun,
Thanks very much for this. I've replied below. * Shaun McCance: > On Mon, 2006-07-10 at 11:41 +0100, Matthew East wrote: >> 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. Your email was by far the best documentation of the plans and justifications behind the move that I've seen so far, and yes, I've read the above page. It's really worthwhile spending time documenting important decisions taken on irc, for historical reference, especially for something like this that is likely to serious effect downstream. I think it would be really worthwhile to incorporate a combination of your email and the above page into the Mallard wiki page. I really appreciate your explanations, and I think the point about docbook being difficult to do non-linear things with is certainly true. However, I was just not convinced that a "start from scratch with everything" approach would work better than a gradual move towards the ideal help system. That doesn't mean that I am not confident that your ideas for the help system will provide something ideal, because I am. There are some things I want to address about the Moin<->Docbook conversions. > As for new development on Moin<->DocBook conversions, I am > highly (HIGHLY) skeptical about round-tripping between Moin > and DocBook. Put bluntly, I don't believe it's even possible > without semi-intelligent natural language processing. It's > like trying to round-trip between XCF and GIF. I am wholly > open to being proven wrong. That's slightly missing the point: the point is not to have a toolset that is wholly roundtrippable (of course, that's impossible for the reasons you give), the point is to allow contributors to work on a wiki with a simple markup, and produce valid xml that works with our stylesheets. That certainly is achievable, and will be by the next release cycle. > I do believe the format I'm putting together will be very > conducive to WYSIWYG-esque[1] editors. It is explicitly > written to be tool-friendly. Flat block structures make > life so much easier. There's a big pool of untapped > possibilities for user interactions for writers. I'm > talking like Olympic swimming pool here. If there is to be a format change, I think it's up to us to make sure that the tools for the new format are at least as well advanced as those for docbook (or better). So, $format->html (no brainer), $format->pdf (hopefully this can do better than the docbook tools!), $format->Moin and finally Moin->$format. I think these should all be in place before the Gnome docs and downstream docs switch. Hopefully, as you say, much of this will be easy. > Finally, we have lost momentum. Paradigm shifts have a > way of galvanizing people. It gets them excited. They > start doing things they would never have thought to do > before the shift. I tend to think that giving people the ability to contribute collaboratively in a wiki to documentation is the way forward for involving people on a continuing basis. Obviously, that also requires good quality control. Matt -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2.2 (GNU/Linux) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org iD8DBQFEtLZytSaF0w5rBv8RAuZLAJ4ro+hxoAPuuyBKWpI4QEZDfjUC8ACfUMac xjbK0kg9/bVWdGaUMJD7O6g= =bYZl -----END PGP SIGNATURE----- _______________________________________________ gnome-doc-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnome-doc-list
