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.