[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Start of documenting DITA design principles
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:
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
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:
<title>This is a title</title>
<sectionbody><p>Mixed content here</p></sectionbody>
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.