Open Week - another docs day?

[Phil Bull]

Hi Matthew,

On Fri, 2009-09-25 at 08:27 +0100, Matthew East wrote:
> I like the idea, but am just turning over in my mind whether this is
> something that is suitable for OpenWeek, or maybe a separate session
> some other time. Mallard isn't currently part of our tools and may not
> be something appropriate for potential new contributors to the team.
> I'm wondering whether introducing them to two document formats might
> be a bit off-putting at the stage that we are talking about. It's not
> something currently necessary to contribute to the docteam so would it
> be relevant?

I think that the main difficulty people have is in learning a strict XML
format. Whether they learn DocBook or Mallard doesn't matter - the
skills they learn with either should be transferable. The Mallard spec
has a nice "DocBook Element Reference" [1] which should help people to
convert between the two.

Since Mallard is conceptually simpler (and more fun to write in!), I'd
prefer to train people in that and let them fiddle with DocBook if they
like. IMHO, DocBook has lots of baggage which results in a steeper
learning curve and requires beginners to worry about silly technical
details.

I understand that new contributors wouldn't be ready for DocBook
immediately if we only trained them in Mallard, but we could do some
follow-up work to fill them in on DocBook's quirks.

> It occurred to me that a talk on Mallard might be something more
> useful for existing contributors to the docteam, so that we can think
> more about whether/when to switch and can prepare for doing so if we
> decide to.

The format itself is a breeze, and I don't anticipate anyone having
problems with the actual markup. The interesting bits are the changes
we'd need to make to the way we write and organise material.

Thanks,

Phil

[1] - http://www.gnome.org/~shaunm/mallard/docbook.html

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