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

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

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.

Cheers,

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

ekimber@innodata-isogen.com
www.innodata-isogen.com