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


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

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

Subject: Re: [dita] Software Bias in Current DITA Design and Documentation

Physically putting three topics on the same Web page clearly puts them closer together, and that is one potential result of physically nesting. That said, the chunk attribute removes some of the distinction between physically nested and logically nested topics, since you can move from one to the other as part of output processing.

If a specializer wanted to create special tasks for "subtask" and "overview task" they could - it is entirely a choice of what work you want to do via the doctype and what work you want to do via authoring guidelines.

In IBM's case, we haven't created separate specializations for supertasks because it would double the number of doctypes we needed to deal with - a supertask, a superconcept, a superreference, a supertopic... So we weighed the usability hit of educating writers to use task for both subtasks and overviews vs. the usability hit of doubling the available doctypes (and, as a strategy, doubling the number of all future nestable specializations) and went for authoring guidelines.

Re the purpose of section: You're right that the current spec does not require section headings to be non-unique, and I am talking of current usage practice within IBM rather than normative requirements. That said, if you're wondering why we have sections at all, given that nesting topics provides the same functionality, it's the existence of repeating headings like "Purpose" and "Syntax" that clearly are not topics in their own right but merely divisions of an existing topic.

So I do get nervous when we talk about nesting sections and giving them unique titles - at that point I do think there is even more potential for confusion between topics and sections. I'd prefer to make them more distinct from one another, and thus easier to choose between.

Michael Priestley
IBM DITA Architect and Classification Schema PDT Lead

"W. Eliot Kimber" <ekimber@innodata-isogen.com>

01/17/2007 04:39 PM

Michael Priestley/Toronto/IBM@IBMCA
Re: [dita] Software Bias in Current DITA Design and Documentation

Michael Priestley wrote:
> I believe section is primarily for regular or repeating headings - the
> kinds of ones you would generate in a specialized case. Wouldn't these
> subtasks have unique titles, eg "Replacing the framitz"?

That may be the original motivation for section but I don't see how
anything in the language spec or the DTD design would suggest that
limitation in its use. While the examples in the language spec only
refer to subdivisions within reference topics I'm sure we can think of
equally useful examples in concept topics.

But in any case, in my task example, removal and replacement may be
consistent sub-tasks that occur in a set of consistently-structured
tasks and it would, I think, be consistent with the above interpretation
of section, to use it for holding these subtasks (specialized as
"subtask", perhaps?).

> The main difference between nesting topics and nesting sections would
> seem to be that topics require an ID - perhaps that is a bit heavy
> handed, if you're certain that the subtask will never be reused or
> referenced, but it doesn't seem like a bad precaution against
> reusers/referencers coming up with cases you didn't think of it when you
> created it.

I think the bigger potential problem, or at least confusion factor, is
that the containing task may not itself have any steps, which at least
some users (based on recent traffic on the DITA user's list) thought
that task requires steps (it doesn't).

> Sum: if you make the subtasks actual nested tasks, then
> reusers/referencers can make their own decisions about whether it can be
> useful in their context (a different question from whether it stands on
> its own). If you make them sections, then the reuser/referencer's
> options are limited.

This response brings up the issue of what, if anything, is implied by
physically nested topics (that is topics that are structurally children
of another topic) as opposed to the same topics organized into a
hierarchy via a map or related links?

For example, I really don't want a task whose title is just "removal"
because if it is ever used in isolation it's purpose will be ambiguous.
On the other hand, if the task will always be presented in the context
of a parent topic that establishes the "what is being removed" context,
then it would be odd to have a rendered hierarchy like:

1.1 framitz replacement

    1.1.1 Removing the framitz

    1.1.2 Replacing the framitz

(actually, now that I write it this particular isn't too bad but
different content could get a little silly).

The spec as currently written doesn't say much about topic nesting and I
don't know what the tool kit does, but hopefully nothing special.

But Michael's response seems to imply that there is a stronger
relationship between nested topics than other topics (otherwise there
would be no useful difference between having nested topics and separate
topics organized via a map).

Obviously there's authoring convenience to nested topics but should
there be a stronger implication? And if there should be, what is it?

Note too that the storage organization of topics doesn't in any way
affect their re-usability, at least as far as DITA-defined semantics are
concerned (some CMS tools may require re-usable topics to be individual
files but that would be a tool limitation, not a DITA limitation).

> The rationale for identifying unique headings as topics is to err on the
> side of maintainability - if it's a heading, and it has unique
> information, then it's a legitimate destination for references, and it
> makes sense to enable it at creation time, rather than creating a
> bottleneck at first use that requires the destination to be edited to
> change it from section to topic.

I think this is a reasonable rule of thumb and general practice--my
question is whether or not the spec should *require* this practice in
all cases by disallowing any other solution, especially when we can
identify use cases where there at least appears to be a strong argument
for a single-topic solution.


W. Eliot Kimber
Professional Services
Innodata Isogen
8500 N. Mopac, Suite 402
Austin, TX 78759
(214) 954-5198


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