task as sibling to section [was: DocBook Technical Committee Meeting Agenda: 18 October 2006]

["Grosso, Paul" <pgrosso@ptc.com>]

> -----Original Message-----
> From: Steven.Cogorno@Sun.COM [mailto:Steven.Cogorno@Sun.COM] 
> Sent: Monday, 2006 October 16 19:27
> To: Grosso, Paul
> Cc: DocBook Technical Committee
> Subject: Re: [docbook-tc] DocBook Technical Committee Meeting 
> Agenda: 18 October 2006
> 
> >> 9.  Unfinished business: RFE 1097183: Allow Task as a sibling
> >> of sections
> >
> > I'm opposed to this.  Having multiple division-like
> > things as siblings is a bad idea, and even if we have
> > that in places now, I don't want to make things worse.
> 
> 
> Can you elaborate why you think it's a bad idea?

1.  It complicates the DTD, making it harder for authors 
    to understand how to mark up their documents.

2.  It complicates the resulting instances, assuming
    the authors have used such markup.

3.  It breaks hierarchy, making things like numbering
    sections difficult (do you number tasks and sections
    as if they are the same kind of thing or not?).

4.  It destroys the semantics of what it means to be a
    section.

and probably more.  My 25 years of experience tells me
it's the wrong thing to do.

> 
> > If you want to use DITA, use DITA.  Let's not make a
> > mess of DocBook.
> 
> 
> That's not a productive answer.  Technical writing is quickly  
> becoming very modular.  Whether we like it or not (personally, I'm  
> not a fan), we have to address those needs if DocBook is to remain a  
> relevant standard.

Well, I think it is a productive answer, but perhaps it's
too much shorthand for you to appreciate.

For 20 years now, SGML/XML has had DTDs with the idea that
the you use DTDs to model your data, and if you have different
data and/or different processing needs, you make a different model.

CALS came along, and some product vendors (now mostly extinct)
developed special applications that just worked with "the CALS
DTD", but they missed the point of arbitrary DTDs.

Then HTML came along, and everyone started cramming all sorts
of information into a single DTD, and when that didn't model
what they wanted, they invented new tags or fooled with scripts.

A DTD should reflect the results of an information analysis for
a given application or family of similar applications.  DocBook
has done an excellent job of reflecting the 80/20 needs of the
community it was designed to serve as well as optimizing the
possibilities of allowing private extensions via parameter
entities.

DITA has been developed based on a different information analysis
for a different set of applications under different circumstances.

It makes no sense to look at DITA and try to incorporate all its
elements into DocBook.  Trying to do so only ends up complicating
a DTD that is already so complex it overwhelms beginning users
and turns instances written to such a DTD into the equivalent
of what we used to call spaghetti code back in my programming days.

paul