MHonArc v2.5.0b2 -->
dita message
[Date Prev]
| [Thread Prev]
| [Thread Next]
| [Date Next]
--
[Date Index]
| [Thread Index]
| [List Home]
Subject: RE: [dita] Nested Sections
The problems you are encountering are
ones that I see as common for topic-oriented content - for example, having
a parent topic that includes both introduction and review for its children
(like a parent task providing both <prereq> and <postreq> sections
that apply to the branch of child tasks it contains). Should every branch
of tasks that has a sequence and result become a single task with nested
sections? This is a slippery slope that extends the definition of topic
to first include chapter-level content, and eventually entire books.Some of these problems have been dealt
with at the map level by the addition of elements like <topicgroup>
and <topichead>, which provide ways of grouping or introducing content
without using a full topic, and also of a topicref with only shortdesc
content, which can be used to provide a summary or result in the map without
having to pull in a whole topic with no title (or an ignored title). I've
had conversations with numerous users about how to solve these problems,
at every level of nesting. One solution is to move the conclusion/result
section out of the parent topic, and into a concluding/summarizing topic
as a last child:<topicref type="task" collection-type="sequence"
href=""makingstuff.dita">
<topicref
href=""prep.dita"/>
<topicref
href=""dothis.dita"/>
<topicref
href=""andthis.dita"/>
<topicref
href=""nextsteps.dita"/>" <-- moved out of the parent topic's
model and into a concluding task that has only a postreq-->
</topicref>
When we begin combining the content
at the document level, perhaps the problems become more obvious, but they
aren't inherently new problems, and they shouldn't change the definition
of topic. There are definite advantages to having a predictably structured,
predictably sized topic, and allowing nested sections would remove that
predictability. Technically, topic boundaries provide points for reuse,
for link insertion, and for rich metadata. Our current model encourages
topics to remain relatively simple in and of themselves, and to achieve
complexity by nesting topics - which in turn provides document models that,
even when they are complex, can be decomposed into simple objects, and
are both extensible and integratable by default, rather than those features
requiring extra work.
One of the features of DITA is that
it does enforce rules, and does not depend just on editorial guidelines.
We had guidelines on topic orientation at IBM long before we had DITA;
the guidelines were enough for some groups who had strong editorial discipline,
but it was definitely not enough for others, and we didn't get consistent
chunking at the topic level until we moved to DITA. The initial migration
caused headaches for a number of groups who had historically chunked at
the chapter level, and tried to migrate chapters to topics on a one-to-one
basis. They asked us for nested sections, since that was a better match
for their existing content. We worked with them over time to move their
content into a topic model and out of a chapter model, and the requirement
for nested sections disappeared. We didn't have that opportunity under
the old nested-section model - it took migration into the more restrictive
DITA model to make the change happen, and post-migration we have content
that is generally more consistent, more usable, and more reusable.
We moved to DITA to get away from the
problems nested sections caused: ie, radically different sizes of logical
unit that prevented cross-team integration and reuse. If we allow nested
sections in DITA, I would fully expect the problems to follow.
Michael Priestley
IBM DITA Architect
SWG Classification Schema PDT Lead
mpriestl@ca.ibm.com
I think that we have an inherent
philosophical difference. I would be surprised if you could name a user
of DITA who depends upon the fact that sections cannot nest. You might
be able to name users who do not want sections to nest _at their site_
and _for their users_, but DITA inherently allows them to enforce
those rules and will do so even more after Erik's widely lauded proposal
is incorporated into DITA. I see the changes you propose as much more destructive
than the section nesting one. For example, the invariant that all topics
have a title is embedded in all DITA software and in most people's thinking
about DITA's data model. If we allow sections to nest, we just have to
set up some new stylesheets to handle the different section levels.
I find the argument that we need
to protect ignorant people from themselves only compelling when it does
not cause a burden for knowledgable people. In this case it does.
From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Thursday, November 03, 2005 1:24 PM
To: Paul Prescod
Cc: dita@lists.oasis-open.org
Subject: RE: [dita] Nested Sections
Thanks for the clarifications - that's what I get for commenting without
complete information :-(
I agree there's a mismatch between the customer requirements and the current
model, and I agree changes need to be made to accomodate them. However,
I'm going to keep beating at the issue a bit longer - basically I'd rather
keep the topic model, and occasionally end up with some topics that are
like sections, than break the topic model, and end up with lots of sections
that are like topics (where I fear this would end - not in your case in
particular, but in the community of use in general).
Here's another potential treatment of the model, without breaking the section
nesting rule (albeit breaking tons of others, which just happen to matter
to me less):
learningobject
title
body
questions
question
title
body
question
title
body
conclusion
related-links
To make this work we'd need a number of changes to the existing content
model for topic:
- (for <questions>) allow wrapper elements after the body, equivalent
to <linkpool> or <linklist> but for topics rather than links
- (for the new placement of links) allow nested topics and related-links
to occur in any order
- (for conclusion) allow topics without a title (assuming the heading will
be generated) (would need to add some fallback logic for linking transforms)
We'd need to add new processing etc. to support all this (having a conclusion
topic without a title would in particular cause some pain for our linking
transforms), but I'm hoping this would meet your customer's needs while
avoiding the topic chunking issue.
Thanks for providing the concrete example - it's a lot easier for me to
work through, and I hope I'm not appearing too recalcitrant on the topic
issue. We both want DITA to meet your requirements, my wriggling is an
attempt to do so while preserving what are, for other users, critical architectural
requirements.
Michael Priestley
IBM DITA Architect
SWG Classification Schema PDT Lead
mpriestl@ca.ibm.com
1. The questions are not topics because they are not (in this customer's
context) designed to be meaningful _on their own_. They could refer to
the content above them or the question above or below them.
2. The customer wants the wrapper for the reasons I described below. The
wrapper simplifies authoring. The wrapper simplifies formatting. The wrapper
guarantees that the questions are always together (there might be other
kinds of sub-topics).
3. Your model requires the questions to be the last thing in the topic,
except for another subtopic. But the customer might want "back matter"
for a topic that also makes no sense as a standalone topic. e.g., they
think of the related-links element as following the questions (both for
authoring and publishing).
We're contorting the way they model and think about their system and I
don't really understand how they or we benefit.
From: Michael Priestley [mailto:mpriestl@ca.ibm.com]
Sent: Wednesday, November 02, 2005 7:54 PM
To: Paul Prescod
Cc: dita@lists.oasis-open.org
Subject: Re: [dita] Nested Sections
If you modeled each question as its own topic, you would not need a container
topic called "Questions".
Example:
<learningobject id="x">
<title>...</title>
<body>...</body>
<question>
<title>..</title>
<body>..</body>
</question
<question>
<title>..</title>
<body>..</body>
</question
<question>
<title>..</title>
<body>..</body>
</question
</learningobject>
Underneath the covers, there'd be two specialization modules, integrated
into a doctype that specifies "learningobjects contain questions".
But to the user, this would be very similar to the structure you described
below, just without the container element.
Michael Priestley
IBM DITA Architect
SWG Classification Schema PDT Lead
mpriestl@ca.ibm.com
In a previous discussion, Michael asked why nest sections when you can
nest topics. My opinion is as follows.
If topic-based authoring means anythng then it means that you don't
arbitrarily shred everything with a title into a topic. Topics are
things that have meaning ON THEIR OWN. A section that is inherently
embedded in its context should not become a topic to fulfill an
arbitrary requirement of a framework.
Our customer is in the e-learning domain. He has "questions"
that are
directly related to the surrounding content. The questions are richly
structured like sections. The set of questions needs a wrapper element
to supply a title and organize the authoring experience.
Reusable Learning Object
Information
Information
Questions
Question title
Para
Para
List
Para
Question
Para
List
Table
Para
Question
Para
Table
Para
So in this case I'm not looking for infinitely nested sections. I just
need two levels hard-coded into the specialized topic type. I don't
think that this design is controversial, innovative or unique.
If I turn "Question" into a topic type then I also need to turn
"Questions" into a topic type and its only purpose is to wrap
up other
topics. Plus I cannot default the title. Plus there are content
management and policy implications, because the customer wants all
topics to be content managed objects and all content managed objects to
be topics (in the sense of being inherently designed for reuse). (which
seems quite reasonable to me)
My other use case is wrapping up multiple elements to supply a single
conditional attribute on them.
Para
Section audience="expert"
Para
Para
Section product=""
Para
Para
Para
Para
I would also use this mechanism to conref more than one element at a
time. (I personally prefer this to a range-start/range-end model).
>