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] Nested subsections in specializations

Hi, Paul:

Apologies for the length -- trying to address the significant issues you raise.

The rationale for keeping content objects short and shallow is to encourage designers and writers to create content that is easily consumable and manageable. A content object that has a divided structure that's five levels deep with three items at each level isn't likely to be either.

The rationale for nesting topics is to support drill down into detail. The parent topic gives the high-level overview of the subject matter. If the reader only needs the high-level overview, the reader can stop there. If the reader needs more detail, the parent topic supplies a context for the child topics. To put it another way, a child topic can function either as independently consumable content (that is, as content that can be read on its own) or as part of a composite.

By contrast, divided discourse typically is written as a continuous sequence of text with subdivision. In this approach, Section 4.3.3 is written as a continuation of Section 4.3.2. That is, Section 4.3.3 (and Section 4.3.2, 4.3.1, and 4.3 for that matter) effectively starts in mid-thought. Where existing sections or divisions already stand alone, they migrate much more easily to topics.

To maximize reuse, you should implement topic nesting in the map. You might implement topic nesting in a file if the subject matter of the nested child topics is so closely related that it's convenient to bundle them in a single package. Even in this case, however, each topic should still be independently consumable -- for instance, if a link brings the reader directly to a child topic, the content shouldn't read as starting in mid-thought. Also, if you later discover an opportunity for reuse, it's much easier to move the topic out of the file if the topic has been written as independently consumable content.

To take the Reusable Learning Object as an example, even if you always wanted to package the RLO with the same set of questions (no variance for different deliverables or audiences), you would still want to write each question so it can be read independently. Down the road, you would get added benefits if you discovered a need to create versions of the same RLO with variant sets of questions or to reuse the same question in several RLOs.

Of course, the other reason to implement topic nesting in a file is as part of a phased migration in which the child topics aren't initially standalone treatments of their subject matter. In other words, populating nested topics with non-topic content as a pragmatic step on the path toward reworking the content so topics in form become topics in fact.

The default document type shells nest topics of the same type because a set of closely related topics providing drill down are likely to be treating the same aspect (that is, information type) of the subject matter. The default document type shells are only a starter kit, however, and any composite can be created with the ditabase document type shell. In principle, a tool should let a site administrator select the topic types and domains and assemble a new document type shell.

It's natural for designers who have created a markup to want to use specialization to recreate that existing markup -- after all, they put a lot of thought into the markup and would prefer avoiding migration -- but the point of specialization isn't accomodating arbitrary existing markup. The point of specialization is a common type hierarchy. (Let a thousand flowers bloom as a means of cultivating a garden of defacto standard types.) Because the base type for the DITA vocabulary is topic, the DITA type hierarchy has to define topic types if it is to mean anything.

We cannot and should not remove the requirement for designers to analyze their problem domain and their existing markup to determine how best to model the content as topics. In many cases, to get optimal topics, they will need to define more granular content objects than in their existing designs.

Regarding Java, my point is that Java found the right blend of design discipline and flexibility. Skillful marketing helped, of course, but Java was a fundamental paradigm shift for a large portion of its adopters. For the C programmers who knew #include, macros, and structured programming, Java required a new approach -- unlike C++, which continued to support all of the old approaches. Java adopters made the shift and, because of the benefits they received, never looked back.

In this thread, the requirements for recursive sections have seemed either:

Paul, you've identified your focus as the second requirement. Is that true of the others who have argued for recursive section?

For the second requirement, in the long term, we may need to enhance the architecture -- after all, nested sections can only group some elements.

In the short term, do the requirements for substructure arise from analysis of the problem domain or from an existing markup? Are the substructures nice to have or essential? For instance, the Questions container from the RLO seems like something that might well be nice to have but likely isn't essential because the Question elements are unambigous for authors and for processing -- it would be trivial, for instance, for an XSLT rule to wrap a container around the Question elements. Can you provide a use case where more substructure within a single topic is essential?


Erik Hennum

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