RE: [dita] documenting DITA design principles

> 
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:]
Sent: Monday, October 03, 2005 
  1:10 AM
To: 
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.