RE: [dita] Thoughts On Sections

[Michael Priestley <mpriestl@ca.ibm.com>]

ditabase, or nested generic topics,
both provide for a large document starting point. During migration, at
a minimum I'd expect every subheading should go to a nested topic by default,
unless it's a recognized repeating heading (eg Example or Usage etc.).

If we migrate everything to nested sections,
then they will only have to remigrate everything to topics - there's no
benefit to being in nested sections, and there's no evolutionary path to
becoming more topic oriented. Whereas if they are migrated to topics initially,
they can over time rewrite each one to be more independently readable.

IE, we already support this evolutionary
model of DITA adoption, it's just about having minimally smart migration
transforms. 

Michael Priestley
IBM DITA Architect
SWG Classification Schema PDT Lead
mpriestl@ca.ibm.com

"Rob Frankland" <torobf@earthlink.net>

10/28/2005 12:30 PM

To	"'JoAnn Hackos'" <joann.hackos@comtech-serv.com>, "'Paul Prescod'" <paul.prescod@blastradius.com>, <dita@lists.oasis-open.org>
cc
Subject	RE: [dita] Thoughts On Sections

This discussion really addresses a critical conundrum
with DITA in general.
The line of thinking that stresses writing reusable concise topics is
admirable. For users just adopting DITA, one of their biggest concerns
is
how they migrate their existing content into DITA. If the integration of
legacy content requires huge rework, only the largest, most well-financed
groups will take that the plunge. 

I think this tips the argument in favor of the approach Paul has suggested.
It accommodates both points of views. It enables new content to be created
expeditiously for single-sourcing and allows legacy content to be imported
with less effort.

Rob 

Rob Frankland
12408 Kallgren RD NE
Bainbridge Island, WA 98110-3328
Phone: 206-780-8850
Email: torobf@earthlink.net

-----Original Message-----
From: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com] 
Sent: Friday, October 28, 2005 5:48 AM
To: Paul Prescod; dita@lists.oasis-open.org
Subject: RE: [dita] Thoughts On Sections

Would it not be preferable to advise users to consider developing these
subconcept statements as individual topics that may then be more easily
reused in other contexts? In most cases, the nesting into two or more
levels of information is a formalism preferred by the writer rather than
a useful construct for the reader. In most instances, when I review
these structures, they are poorly structured. I know that we can't
enforce good writing practices, but it's interesting to think we might
try.

If the authors were asked to write smaller conceptual topics, with
better structuring of information to make the information more flat (and
therefore perhaps more understandable), we could stay with the original
design. If the nesting is really that important to understanding in the
output context, the nesting could occur in the ditamap rather than in
the topic itself. The smaller conceptual topics would also be more
readily available for reuse in contexts where they should be standalone.

Just some thoughts
JoAnn

JoAnn T. Hackos, PhD
President
Comtech Services, Inc.
710 Kipling Street, Suite 400
Denver CO 80215
303-232-7586
joann.hackos@comtech-serv.com


-----Original Message-----
From: Paul Prescod [mailto:paul.prescod@blastradius.com] 
Sent: Friday, October 28, 2005 6:41 AM
To: dita@lists.oasis-open.org
Subject: [dita] Thoughts On Sections

On last week's call we discussed several different approaches to
sections. My personal opinion on the current section element is that
they are simultaneously too strict and too loose. We've discussed at
length the sense in which they are too loose: they do not provide any
guidance for authoring and overlap almost exactly with the content model
of paragraph.

On the other hand, sections are more strict than HTML "DIV" elements
in
a very important way: they cannot be nested. Some of our customers have
a need for "grouper sections" that can wrap up other sections
in their
specializations. Basically their topics are not necessarily flat. For
privacy reasons I'll make up an example structure:

Part Description
                
Subparts
                
                 Subpart
1 description
                
                 Subpart
2 description
                
                 Subpart
3 description
                
Use contexts
                
                 Context
1 description
                
                 Context
2 description
                
                 Context
3 description

The customer sees the "Part Description" as the topic level because
the
subparts are meaningless to the reader out of context of the parent.

Therefore I feel that in the loose, designed-to-be-specialized base DITA
topic type, sections should be nestable. Another key reason to allow
sections to nest is to have a body-level container that can serve the
"generic wrapper" role that phrases do at the inline level. Generic
wrappers are useful as a basis for specialization, as a place to put
filtering attributes and as a way to logically conref a set of content
elements at once.

I propose short-term and long-term directions for sections:

DITA 1.1: they should be loosened to be generic wrappers that can nest.

<!ENTITY % section.cnt "(#PCDATA | %basic.ph; | %basic.block; |
%title;
|  %txt.incl; | section)*">

DITA 2.0: they should be tightened to be generic wrappers _of body
elements_ with zero or one titles and no PCDATA.

<!ELEMENT % section.cnt "(title? , %basic.block;)">

If we could agree on this direction then we wouldn't need a new
structured-section element. But if it is important that section have
basically the same content model as paragraph plus titles (I'm not sure
why) then we probably do need structured-section.

 Paul Prescod