Re: Successor to DocBook

[Shaun McCance <shaunm gnome org>]

First, let me apologize if my posts are coming off
as edgy.  I just feel like I've been repainting
the Hindenburg for the last four years.  I've been
trying very hard to create good user documentation
within our current setup, and nothing seems to be
working.  I'm tired, and I want to finish this.

On Wed, 2006-07-12 at 06:03 +0200, Karl Eichwalder wrote:
> Shaun McCance <shaunm gnome org> writes:
> 
> > Why not just give all the elements simple and consistent names
> > to begin with?  Nobody can even remember the DocBook elements,
> > so what's the point of catering to that experience?
> 
> The good thing about DocBook is, that it is by now an accepted standard
> in the free software and open source community.  Many developers and
> writers are sufficiently enough familiar with the DocBook markup.  Even
> if some element names are weird, it might make sense to keep them
> because we have learnt them (and beginners can learn them as well
> without too much trouble).

My experience is that very few of these people are
joining the Gnome documentation effort.  They're
off writing largely geeky docs (witness the sorts
of docs the excellent Fedora documentation squad
usually produces).

By and large, when we do actually have people who
want to contribute to Gnome documentation, they
are not seasoned *Nix documentation folks.  They
don't know DocBook, they don't know TeX, and they
certainly don't know roff.

> Yes, I'm quite conservative.  I'd say we should wait another 10 years
> before start to push the next DTD/Schema onto the community.  ATM, the
> problem is not the markup per se, but the lack of a free XML editor.  We
> need a combination of oxygen and emacs (psgml/nxml/xml).

If I'm still the Yelp maintainer in 10 years,
somebody please have me committed to an asylum.

I completely agree that the lack of a free XML
editor is a serious hindrance to our ability to
recruit quality tech writers.  I've seen various
people try to address this, and one thing that
always causes problems is that DocBook is hard.
Making pretty buttons for all the inline markup
doesn't change the fact that you have too much
inline markup.  Now you just have a cluttered
user interface.

As for new formats and sticking with the old,
I figure DocBook 4 has about three solid years
of life left, and then another two years or so
of a slow and agonizing death.  Anybody sill
using DocBook will switch to DocBook 5.

DocBook 5 is a fairly fundamental departure
from DocBook 4.  It shares many of the same
markup elements, to be sure.  But there are
radical changes in ways that will have huge
impacts on folks like me that write tools.

We will have to invest time into a transition
within the next few years either way.  I would
really rather spend that time transitioning to
something that can really fulfill our needs.

> > As for existing tools, no existing tool is going to get the
> > link mapping correct.  You might get some formatting fluff
> > for free, but that sort of stuff is labor cheap compared to
> > the rest of the work involved.
> 
> There is some truth about your statement.  But do not forget that
> people have written keyboard macros and editor extensions to make
> DocBook editing less cumbersome.  There are also DocBook converters.  So
> more tools exist than just formatting tools.

This is all true.  My general experience with
DocBook tools is that none of them go all the
way.  My HTML converters, for example, are not
fully conforming.  The "standard" ones, on the
other hand, are obtuse and painfully slow.

The DocBook PDF tool chains I've seen aren't
very spectacular, often due to the fact that
XSL-FO processors aren't very good.

This is perhaps a good time to point out that
I consider the documentation system to be a
core part of our platform offering.  As such,
I take backwards compatibility very seriously.
DocBook will continue to be a supported option
for documentation for the foreseeable future.

> Yeah, DITA is complex...  but it is topic oriented.
> 
> > People seem to think that this is nothing more than simpler
> > DocBook.  It's not.  It has nothing to do with DocBook, and
> > there's no reason to pretend it does.  I should call it MIND:
> > MIND Is Not DocBook.
> 
> ;)  I still believe that DooBook is good enough.  If you want "topics"
> use unnumbered section elements; if special link tags are actually
> missing, import them using namespaces.

I've tried for years to make it good enough,
and I just don't think it ever will be.  Not
for what I'm trying to accomplish.

Maybe I'm wrong.  I'm not removing DocBook
support from Yelp, and I'm not strong-arming
anybody.  I rarely use my purported power to
force anything.  Writers are ultimately free
to tell me I'm off my rocker.

--
Shaun