Transition to Mallard?

[Phil Bull]

Hi guys,

I think that now is a good time to talk about whether we should migrate
over to Mallard this release cycle. Here's my appraisal:

ADVANTAGES

      * Simpler syntax than DocBook, easier for new contributors, nicer
        for existing ones.
      * Highly modular. Should be easier to maintain in a topic-based
        manner.
      * Novel linking model. Pages link themselves into the structure.
        No need to maintain linking pages like the main page, or to
        heavily patch new material into the structure (should be nice
        for OEMs).
      * Well-supported by upstream. GNOME docs will soon be in this
        format and we can be involved in shaping its further
        development.
      * Better navigation. Links have captions. Breadcrumb bar. Easier
        for users to find things.
      * It's a new feature. People like new features :)

DISADVANTAGES

      * Requires modifications to the toolchain. I don't know how
        smoothly we can do this. For example, can we get Mallard and
        Rosetta working together nicely before release?
      * The conversion would take quite a lot of work, distracting from
        writing new documentation.
      * People will need to learn how to write Mallard documents.
      * Would be going into an LTS release so would require extra
        testing.
      * Support is still young. There could be serious bugs that we
        haven't seen yet.

I think that the advantages, both to us and our users, significantly
outweigh the disadvantages. The Mallard workflow, and the results that
you get, are far superior to what we have now. It would solve a lot of
problems. I'm confident that we can do the initial conversion in a
couple of weeks. The toolchain issues would require further research,
but I don't think that they're insurmountable.

What do you think?

Thanks,

Phil

-- 
Phil Bull
https://launchpad.net/~philbull