Re: [Emo-dir] quick-start guides

[Wes Hardaker <[e-mail]>]

"Salz, Rich" <rsalz=[e-mail]> writes:

> > 1. As below, do we recommend Markdown over XML or let people choose?
> The authors site currently lets people choose but that can change.
> 
> At the EMODIR call last week, Alice said that statistics show 90% is
> XML and under 10% is markdown, with a smattering of other things.
> 
> So let's pick the top two for now, xml and kramdown.

We should pick ones that we think will be the easiest to get people
started producing stuff, regardless of what the current crowd is using
(because they've been using XML for so long I'm sure it's the most
popular).

To help people they need:
1. an easy to use/edit language
2. an easy to use build tool
3. documentation
4. A list of alternatives to 1 and 2 if they wish to explore

What the right answers are to 1 and 2 I'm not sure.  To *me*, markdown
is far easier for people to understand and get started with because it's
syntax is probably already understood by new folks.  I can still never
remember the right XML tag for a list, etc, and whether or not it should
be nested inside a <t>, etc.  One downside of the markdown format(s) is
that it's unclear how to do the extra required stuff (wg name, ipr
statements, etc) without a clear template to start with because we
require so much extra metadata.  Once I got my own template to copy each
time, life became much easier.  But I probably wrote 2-3 drafts in xml
that I wanted to do in markdown but couldn't figure out how to get
started quickly and didn't spend the time until later to figure out all
the right magic syntax in markdown.  And there's the rub: both formats
require some magic syntax.

I think MT's build environment is great, except that I actually don't
understand much of it when I glance at it the first time.  It's an
overwhelming makefile and needs a better getting started guide (IMHO; no
offense intended -- it could have just been me and my minimal brain).
So for *me* I actually forked my own copy of a simplified version that I
use as a template because my minimal brain understands it better.

-- 
Wes Hardaker
USC/ISI