RE: [dita] documenting DITA design principles

["Esrig, Bruce (Bruce)" <esrig@lucent.com>]

> Principle 2: Only One Way To Do It

 

Principle 2 is not always valid. Sometimes it's necessary to fall back to a more flexible pair of principles:

 

"Offer a path to a context-appropriate result from every context"

"Support consistent functionality along all paths".

 

The "context-appropriate result" is not necessarily the same along all paths.

 

This came up during the design discussion for mentions and index entries.

 

If we do not accept the following sort of structure (where mention is <term> or a similar element):

 

<indexterm>major index group

   <indexterm><mention>term</mention>

   </indexterm></indexterm>

 

We would have to fall back to a weaker ad-hoc feature such as

 

 <mention add-to-index="y">term</mention>

 

This is weaker in the sense that adding an attribute is not complete for index entries. That is, there are things that you can say in the full indexentry markup that might be rather awkward to map into attributes of another element. So you would have to accept a "context-appropriate result".

 

The "context-appropriate result" in this context is an index term at top level, since indexing isn't the primary function of mentions. A mention allows you to throw a term into the index as long as you don't mind having it appear at top level. If your primary purpose is to make a really good index entry, then you can't rely on mention to support what you want. You have to use <indexentry> and <mention> side by side.

 

 

===========

 

Another principle that we ought to be explicit about is

 

Principle 6. Design the language, not just the markup.

 

This would mitigate several debates, such as the one mentioned in Principle 4 below. Also the recent dialog between JoAnn Hackos and Robert Anderson over a sequence of alternatives, all optional.

 

It's an inherent and intentional limitation of many structured languages that combinatorial constraints cannot be stated in the language. You can say whether an item is required, but there is no practical way of saying which combinations of a pool of items are required or permitted. Formally, it is possible, but you have to do user-unfriendly things in the markup in order to specify required and permitted combinations of items.

 

So in addition to the technical specification of the permitted markup, we need a supplementary specification (perhaps the language reference) that states which combinations of markup are supported for certain purposes that are considered part of the core functionality of the language. This could even be extended to use cases and best practices that reveal how markup is combined: typical uses of maps, good ways to use external files and conref material from them. The use cases and best practices should be published in conjunction with the language design so that readers of the published materials can put the whole picture together.

 

Best wishes,

 

Bruce

-----Original Message-----
From: Paul Prescod [mailto:paul.prescod@blastradius.com]
Sent: Monday, October 03, 2005 1:10 AM
To: dita@lists.oasis-open.org
Subject: [dita] Start of documenting DITA design principles

I think that a helpful step in our design process would be start documenting the design principles that underlie DITA present and future. I had an action item #00003 to propose some design principles from the point of view of an authoring vendor.  I would encourage others to offer other principles from their other perspectives.

 

 

This is a proposal of design principles that should guide future developments of the DITA language. This is a small subset of all of the design principles that must be considered. The document represents a starting point. Because design principles often conflict, they cannot be treated as hard and fast rules.

 

Principle 1: Organizing elements into categories

 

The mental model of authors and the user interface of authoring tools tends to follow certain age-old principles of publishing. Objects tend to fall into categories:

• Documents
• Chapter-like things
• Containers that group other things (examples, figures, lists)
• Paragraph-like things
• Inline text containers (bold, phrase,

 

In addition, the demands of modern information management also require metadata like topic metadata and indexes.

 

The more these categories can be maintained, the easier it is for users to understand the schema by mentally placing things in buckets. For example, a user should be able to infer that lists are not valid children of an italic element because in DITA the pattern is that inline elements go within paragraphs which go within containers etc.

 

Principle 2: Only One Way To Do It

 

Where possible, avoid giving the user two different ways to express the same thing. First, they will naturally ask whether the two different ways have a different underlying meaning. They may even imagine different meanings where there are none. Second, the two different syntaxes give implementers leeway for mistakes. They may implement only one or implement them differently.

 

Principle 3: Semantic Consistency

 

Elements should have the same meaning in multiple contexts. And the same meaning should be expressed using the same element regardless of the context.

 

Principle 4: Minimize Use of Mixed Content

 

Mixed content should be carefully managed. A limitation of DTDs and W3C Schemas requires that any element that contains mixed content also have an unordered and repeatable content model. This disables important types of validation and authoring tool guidance. Mixed content patterns can be avoided by using wrapper elements like this:

 

<section>

            <title>This is a title</title>

            <sectionbody><p>Mixed content here</p></sectionbody>

</section>

 

In order to allow specialization, there is often pressure to increasingly loosen the base DTD or schema. In some cases it may make sense to make an “abstract” element that is designed only to be specialized and which is never directly authored. Then an authoring-oriented specialization can be created. This technique should be carefully managed because it infringes on the rule of trying to avoid having two different element for the “same” thing.

 

Principle 5: Borrow From Other Languages

 

Users will often be familiar with pre-existing languages like HTML and DocBook. Where possible, these languages should be the starting point for new designs. Differences from those languages should typically be justified in terms of DITA’s different design goals and principles, or in terms of lessons learned since the standardization of those languages.