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] Nesting topics

"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

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