Re: [dita] Nesting topics

[Michael Priestley <mpriestl@ca.ibm.com>]

"Paul Prescod" <paul.prescod@blastradius.com>
wrote on 11/06/2005 06:18:45 PM:
...
> If I were of the belief that strictness of topic-
> orientedness is important at all levels of DITA then I would 
> actually argue that topics should be disallowed from nesting. But
> instead the most dedicated advocates of topic-orientation are 
> promoting sub-topic structures. I would appreciate it if you would
> help me to understand your position better. 

There are cases where nested topics
make sense. For example, reference topics, in which the document describes
eg a C++ class, and contains subtopics for each method.  Install
instructions are another common one.

Nested topics do allow people to author larger, less
topic-oriented content, but that's also sometimes appropriate as part of
the workflow for becoming topic-oriented. For example, a beta release of
a software product might include only installation instructions and a getting-started
tutorial, all in a single readme or doc file. Over time this information
will become more formal and topicized, and some or most of the content
will move out of a single source document and into separate topic documents
that can then be assembled or reused more readily.

> I personally dislike 
> nested topics both from the points of view of information 
> architecture (make them standalone!), content management (make them
> separately tracked objects!) and simplicity (maps and nested topics
> present two different ways of establishing a hierarchy of topics).

Maps can target topics whether they
are authored standalone or authored within a larger document. The maps
can already be used to add links to and from nested topics; and with the
implementation of the chunk attribute, it basically won't matter whether
the topics are authored in nested form or not in terms of the output.

> Another part of this that I seem not to understand
is the argument 
> that making a section into a topic makes it "more reusable"
-- "just
> in case someone wants to reuse it." I find this hard to understand
> for two reasons: 1. Making something reusable is typically a 
> conscious choice involving content rewriting. 

Not true at the topic level. If it's written to be
easily understandable on its own, then it also should be easily reusable
on its own. But the goal of the author is not necessarily reusability,
but usability. The goal of the reuser is reusability, and that's why reuse
should be in the hands of the reuser - they're the ones that know their
criteria for reuse, not the original author.

>2. Every element with 
> an ID is reusable in DITA through conref. Topics are only "more
> reusable" to the extent that that is how they are written and
> managed. 

Not at all. Topics are addressable and manageable
by maps. Sections etc. aren't. This is a deliberate level of abstraction
in the map to prevent them from turning into detailed paragraph-level outlines.

>In my (probably naïve) opinion, if a topic is
meant to be 
> reused indepdendently then it should be its own, context-independent
> file with its own metadata, managed independently on the CMS or file
> system. And if it is not meant to be reused independently then it
> should not be a topic.

Maps allow reuse at the topic level in a scalable,
CMS-independent way. With the chunk attribute added, the reuse will also
be independent of the file system as well (ie regardless of how topics
are stored, they can be arbitrarily combined or separated from their neighbors
on output). In the meantime the topics still represent units that the map
can control from a linking perspective, regardless of whether they are
nested or not.

> It doesn't matter whether you are using a CMS
or file system. The 
> more advanced your tools, the less you need to depend on file 
> nesting in order to see some context. The more primitive your tools,
> the more you need separate files to help you find your content and
> manage your locking.

We allow topic nesting because there are cases where
it makes obvious and necessary sense (as with API docs, tutorials, install
instructions, etc). We don't allow section nesting because, since we already
allow topic nesting, we shouldn't need to. 

I agree there are cases we need to address where,
especially at the specialized level like task, we need more flexibility.
But allowing section nesting, as I described in a previous post, compromises
the reusability of content. Nesting topics does not prevent a map from
getting at the topic; but turning topics into sections, and turning chapters
into topics, does prevent a map from getting at the topic, which prevents
reusers from being selective about their reuse, which in turn forces them
down the old familiar road of large shared documents full of conditional
properties, which is exactly the problem that topic- and map-based reuse
is designed to solve.

> By the way, it is hard to reconcile the following
statement with 
> DITA's topic nesting capability: "...topics have no internal
> hierarchical nesting; for internal organization, they rely on 
> sections that define or directly support the topic."
> 
> http://www-128.ibm.com/developerworks/xml/library/x-dita1/
> 
> I suppose this is true if you define "internal" very carefully
but 
> my team found it a confusing statement.

The article should be updated to be more clear. We
do define the structure of a topic elsewhere, hopefully more clearly, for
example in the architectural spec section "Topic structure".

> And while I'm on the subject: can someone explain
the reason that 
> the type-specific doctypes[1] disallow nesting of other topic 
> types[2], but generic "ditabase" topics have no such limitation[3]?
> Obviously the DITA team went to quite a bit of work to make them 
> inconsistent but it isn't clear to me why that is.

ditabase is designed as the kitchen-sink DTD that
supports authoring all topic types and domains in a single document type,
with as few rules as possible about how to combine topic types at authoring
or delivery time.

The type-specific doctypes are for authoring more
distinct information-typed units. For example we can point at a task authored
in task.dtd and know that the target contains only task-oriented content,
with no mixed-in concepts or reference material.

That said, anyone can create their own DTDs following
the integration rules in the spec, and it's still valid DITA. The DTDs
in the package (as distinct from the .mod files etc.) are intended to show
possibilities rather than limit them.

We should definitely be clearer about the DTD/xsd
doctype shells in the spec. We currently don't even mention the doctype
(DTD) files by name, we just say how to create new ones.

>...
> 
>  Paul Prescod

Michael Priestley