OASIS Darwin Information Typing Architecture (DITA) TC

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

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

mpriestl@ca.ibm.com

http://dita.xml.org/blog/25





"W. Eliot Kimber"
<ekimber@innodata-isogen.com> 
01/17/2007 04:39 PM




To
Michael Priestley/Toronto/IBM@IBMCA


cc
<dita@lists.oasis-open.org>


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


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