Re: Successor to DocBook

[Matthew East <mdke ubuntu com>]

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