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

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

Michael Priestley wrote:
> 
> 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.

Hmm. Looking at the chunk attribute I think I see what you are getting 
at: physically nested topics could be taken to have an implicit chunk 
value that means "render as a single physical unit of access" (e.g., a 
single Web page or help entry).

That seems reasonable with the following caveats:

- The chunk attribute (and the semantics of "chunking" in general) are 
by the admission of the architecture spec underspecified, to the point 
where there's not enough useful definition to actually allow any 
reliable behavior. So we'd need to crisp up the semantics of chunk 
before we could define this behavior.

- chunk= would need to be specifiable on topic directly so that you 
could override the implied default behavior.

But I don't think I would object to having nested topics imply, by 
default, that they are rendered as single "chunks"--I think that would 
be consistent with both what most authors would expect and the 
convenience factor of nesting topics in the first place. And it could be 
overridden at the map level or (by adding chunk= to topic) at the topic 
level.

> 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.

Of course--the question is whether it's reasonable and/or appropriate to 
allow it all in a single topic.

> 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.

Hmmm--I think this is the essence of our difference on this topic: you 
say "that clearly are not topics" in this context but discount my same 
assertion in other contexts. I could just as easily make the argument 
that sections within reference sections should be subordinate topics 
(but I wouldn't because I happen to agree with the design of reference 
topics).

That is, there is an inconsistency here that reflects an inherent and 
unavoidable fuziness about what is and isn't or should and shouldn't be 
a topic or a section. My instinct, in a standard of DITA's generality, 
is to err on the side of permissiveness.

Essentially I'm saying that it's hard to find clear evidence for a 
consistently-applied design principle on when one should or shouldn't 
use topics or sections based on the design of the three base 
specializations. The question is does that reflect inconsistency in the 
design (possibly reflecting its iterative and pragmatic development 
history) or does it reflect a failure in the specification to explain 
how there is in fact consistency?

It is the nature of document types developed over time to sometimes be 
inconsistent, but in the context of a standard we have an obligation to 
try to be as consistent with our understood principles as we can be. In 
the case of section vs topic I think we need to do better.

> 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.

Doh! I just realized what you're getting at--I hadn't realized that the 
various subcomponents of taskbody are themselves derived from section 
(it should have been obvious because there's nothing else they could be).

So OK, I understand your objection to section nesting and I agree (for 
now I am conceding that, at least in general, section nesting is not 
required, although I'm not convinced that disallowing it is the correct 
thing to do from a standards standpoint).

Given that, then maybe the appropriate thing would be to allow multiple 
steps elements and restore the option of giving them a title (since they 
are themselves sections) or, perhaps, allowing multiples but disallowing 
multiple occurrences of the same local element type, if we decide we 
feel strongly about disallowing unique titles for sections.

Hmmm.

I'll also observe that procedural information tends to be the most 
complex and sophisticated in technical documentation and, at least 
relative to real requirements I've dealt with over the years, DITA 1.1 
is not anywhere close to sufficient to satisfying those requirements, at 
least at first blush (it may be that many of the requirements can be 
satisfies by rethinking how the information is organized and presented).

I'm thinking, for example, of even simple things like being able to 
group steps within a single procedure, for example to associate specific 
admonitions with them or to label them as a group or to allow them to be 
re-used as a single unit.

But that is all stuff we'll have to think about post 1.1 of course.

Cheers,

Eliot
-- 
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