OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

docbook message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

Subject: RE: [docbook] Re: (don't) Allow Task as a sibling of sections

I actually find the idea of a task as a superordinate of a procedure valuable, but perhaps that is because of a number of years spent in human factors explaining to writers the importance of context when describing procedures.   I think the task element properly wraps a procedure with the other things that are useful to know when exercising the procedure.  While the same thing can be done with templates, I find the addition of the element makes the job of teaching people to use DocBook easier.

However, I conceive of it as a block element, not an element representing the hierarchical structure of a document.  I want tasks to have a consistent appearance when they are presented, and hierarchical elements need to be differentiated based on their level in the hierarchy or they tend not to serve part of the purpose of hierarchical elements -- letting the user know where they are in the hierarchy.

While I agree the marketing of DITA is quite effective, I find the drive to make DocBook another DITA makes me uncomfortable.  I think we need to actively present DocBook as what it is, a mature, effective method for encoding technical information.  DocBook allows presentation of the information in multiple output media and easily supports content reuse, within a single document or across documents.  Getting started with DocBook is faster and easier than getting started with DITA.  While the modularity and extensibility of DITA is in many ways impressive, I have worked on books, Web sites, and help systems using DocBook with trivial extensions (a mapping element for help system organization, a marker for indicating the contextual linkages into a help system, and some inclusion operators to support content reuse) for a number of years.  I think the noise over DITA has, indeed, led a number of organizations to ignore DocBook, but perhaps that is a sign that we are not making enough noise about DocBook rather than of technical superiority of DITA.  This is not to say that DocBook should ignore the technical innovations of DITA, but rather that if they are integrated into DocBook, it should be in ways that provide valuable extensions to DocBook rather than in ways that make it another DITA.



-----Original Message-----
From: Norman Walsh [mailto:ndw@nwalsh.com] 
Sent: Wednesday, January 21, 2009 8:35 AM
To: docbook@lists.oasis-open.org
Subject: [docbook] Re: (don't) Allow Task as a sibling of sections

"Grosso, Paul" <pgrosso@ptc.com> writes:

>> DocBook Technical Committee Meeting Agenda: 21 January 2009
>> =============================================================
>>     RFEs to be considered
>>       1097183  Allow Task as a sibling of sections
> What is the latest thinking on this?
> I know we've discussed it in the past, and I know
> I've said that I don't see the point of trying to
> dita-ize DocBook.  Sections are fine things to have
> in DocBook--why do we need a sibling division called 
> task?  That just makes a mess of the hierarchy.

(What follows is my personal opinion, NOT the opinion of the Chair of
the TC)

I think that RFE, and the others related to topics, have all just been
left on our list because they're part of that nexus of task-related
issues that we decided to tackle post-5.0.

I'm really ambivilant about tasks.

On the one hand, the DITA cheerleaders argue that they're a
fundamental unit of modern, technical documentation. Setting aside my
reservations about DITA, I hate to see DocBook losing mind share
because it doesn't compete feature-for-feature with DITA and it's
marketing machine.

On the other hand, our existing task element seems over-engineered. I
worry that it's too prescriptive and doesn't satisfy the needs of a
topic-based documentation approach. I look at task and I think, "oh,
that's msgset's less complicated cousin."

So, it seems like there's a fair bit of pressure to make some
topic-based structures at another level of hierarchy. But proposals to
do so always look isomorphic to sections, or nearly isomorphic, to my

> Since this RFE is still on our list, I assume we 
> didn't have consensus to just say no, so can someone
> outline the arguments for why we'd want to do this
> and how it can be done without trashing the hierarchy 
> and unnecessarily complicating both the markup and the 
> processing of such documents?

I find the idea of mixing tasks and sections as siblings utterly

I'm not opposed to a task element of some sort (though I see its
merits as almost entirely political/psychological and I prefer to make
markup decisions on techical merits).

I could even be persuaded (probably) that tasks should be allowed as
an alternative to some existing hierarchies (a book/part/chapter that
has *only* task children, for example).

But mixing tasks and sections as siblings makes a mockery of the
structure of the document. I don't see any rational way to explain the
processing expectations of the elements in such a document. At worst,
there isn't any rational explanation, at best, the explanation is
hideously complex.

At the end of the day, I'd be a lot happier about tasks if someone
could explain technically how they're not just a funny name for
section (or simplesect, perhaps).

Maybe, just maybe, the funny name has such important political and
psychological overtones that it's important to have it.

                                        Be seeing you,

Norman Walsh <ndw@nwalsh.com>      | A hen is only an egg's way of
http://www.oasis-open.org/docbook/ | making another egg.--Samuel Butler
Chair, DocBook Technical Committee | (II)

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]