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: 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:



            <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.


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