Re: Wiki user guide

[Shaun McCance <shaunm gnome org>]

On Fri, 2006-07-07 at 14:19 +0200, karderio wrote:
> Hi :o)
> 
> On Wed, 2006-07-05 at 17:14 -0500, Shaun McCance wrote:
> > On Wed, 2006-07-05 at 23:02 +0100, Joachim Noreiko wrote:
> > > --- karderio <karderio gmail com> wrote:
> > > > Well, this seems somewhat similar to what we had
> > > > already : an index that
> > > > writers would add the content to, except that
> > > > currently we don't have
> > > > the actual index, but a new index that represents
> > > > how things should be
> > > > after reorganisation (at least that is the theory, I
> > > > suppose).
> > > 
> > > Yeah...
> > > the Desktop User Guide is such a monster of a thing
> > > that it hurts my head to think of having two copies of
> > > it on the wiki AND cvs.
> > > (An aside to Shaun if he reads this: Project Mallard!
> > > we need to dice the monster up into topic-sized
> > > chunks!)
> > 
> > Yelp infrastructure should be in place within the next
> > three months.  Once the 2.16 docs are out, I'd like to
> > get any interested documentation writers to sit down
> > with me and actually write some documentation in the
> > new format, as we develop it.
> > 
> > I think you'll find the format pleasantly simple, but
> > it will require you to think differently about content
> > organization.  Fortunately (and unlike linear documents)
> > content really can be written before we've made all the
> > organizational decisions, and we can reorganize stuff
> > with little to no impact on content.
> > 
> > It is coming.  I promise.
> 
> Cool :)
> 
> I must confess, I'm not sure exactly what this consists in, but the more
> I understand it the cooler it seems :)
> 
> Does this replace docbook as <i>the format</i> ? If so, may we as well
> invest in working on the wiki, as online docbook editors may not be so
> useful ?

It does replace DocBook as the format of choice.  The format
of choice will not be any sort of wiki syntax.  The chances
of me adding a parser to Yelp for ''text'' that '''looks'''
like **this** are &--pretty--& $ $slim$@$.

The format is XML, as $DEITY intended.  Here's what you get:

1) The pages you see in Yelp are exactly the pages you write.
   Yelp won't have to look at a deep section heirarchy and
   try to figure out the most logical way to present chunked
   information to the user.
2) The pages each stand on their own.  They are not part of
   a linear structure.  Instead, they are linked into nodes
   that help users navigate and find information.
3) There will be maybe 10-15 block-level elements, with very
   clear semantic purpose and with reasonably well-specified
   presentation.
4) There will be exactly one table model, and it will be the
   one you get with HTML.  CALS tables kill kittens.
5) There will be maybe 10-15 inline elements, with very clear
   semantic purpose.  You know how, in DocBook, you have to
   hunt through 50 or so inline elements, and then there are
   maybe five that sort of closely match what you're trying
   to mark up?  Or you have to use systemitem because there's
   not a specific element for your needs, but then that feels
   dirty because there are *very* specific elements for other
   things.  Let's stop the insanity.
6) The presentational behavior of all automatic text will be
   specified very very very exactly.  It has a huge impact
   on how you write your document, and you deserve to know
   what a processor is going to do with your text.
7) The format is simple enough that sophisticated editors
   will not be difficult.  Writing a wiki-esque thing to do
   online editing should be easy enough.  If people really
   like that workflow, then we can work towards that.  What
   I don't believe in is converting presentational markup
   to semantic markup.  I don't think anything short of
   natural language parsers have any hope of getting the
   conversion right.
8) Documents are pluggable.  I can't even begin to explain
   just how cool this one bullet point is.

Now here's everybody's first chance to get in on the fun:
The code name for the project-as-a-whole is Project Mallard.
This is sort of an inside poke at DocBook.  But Mallard is
a dumb name for a help format.  So everybody:

NAME MY XML FORMAT!

That's right.  You can be forever immortalized by having named
the XML format that will take over the desktop documentation
world.  A decade from now, an aspiring young technical writer
will be learning this format in college, as it will then be the
industry standard.  And she'll be chatting with her professor,
and her professor will say, "When I was your age, we didn't
have $FORMAT.  And we had to walk uphill in snow over broken
glass to get to our text terminals to write documentation in
DocBook.  But that all changed when $PERSON galvanized the
industry by naming $FORMAT."

--
Shaun