DITA 1.2 packages [updated]

Here is a new version of the DITA 1.2
packaging proposal updated based on comments and suggestions received on the
first draft. No major changes to the original proposal from 7 April. A few
additional questions for the TC at the end. Changes are highlighted in blue.

 

We’d like to discuss this during an upcoming DITA TC
call. And, as always, comments and suggestions by e-mail to the list or
directly to me (), Robert (), and Michael () are welcome.

 

The items below are numbered just to make it easier to refer
to specific items in discussions and via e-mail.

 

General comments:

 

 
The proposal is to organize the DITA 1.2 specification
     into a set of six individual

     packages plus an additional combined package as outlined below.

 
All packages include both DTD and XSD doctype shells
     and modules.

 
All packages include catalog files (both XML and text).

 
All packages include
     documentation (DITA source, PDF, and chunked HTML output, and possibly
     HTML Help (chm) and unchunked HTML output).

 
Packages will contain a mix of normative and
     informative (non-normative) materials.

 
Directories and files will be organized and named so
     that they can be combined and

      installed into the same directories without conflict.

 
Except for the combined package, individual packages
     won’t duplicate

     the content from other packages.

 
The Core Package can be used by itself. 

 
Each of the individual non-core packages requires the
     Core package and may

     require other packages.

 
The Core Package plus the Technical Content Package
     gives what

     is available in DITA 1.1 without bookmap and with the addition of
      the Hazard 

     Statement domain, and the Basic Topic and Basic Map document type shells.

 
The written specifications, references, and guidelines
     are being divided into

     smaller independent documents to make them more manageable, to allow

     them to be maintained somewhat independently, to allow readers to

     avoid sections that they may not need or may not be interested in, and to
     make

     it easier to add more structural and domain specializations in the future.

 
The DITA TC and eventually OASIS will be asked to
     approve the specifications, 

     DTDs, XSDs, modules, and related files in the combined package.

 

1)       Core Package

 

a)       DITA 1.2
Core Architectural Specification (introduction, topic, map, and

metadata markup, processing, specialization including constraints).

b)       DITA 1.2
Core Language Reference (map, topic, metadata, map group domain).

c)       DITA 1.2
Utility Domain Specializations Architecture and Language Reference (utilities,

highlighting, xNAL, and hazard statement domains).

d)       DITA 1.2
Processing Guidelines and Examples (non-normative).

 

e)       Basic Topic
document type shell (topic type, no domains).

f)        
Topic type modules.

g)       Topic domain
specialization modules for the indexing, utilities,

highlighting, and hazard statement domains.

h)       Basic Map
document type shell (only map type plus the map group domain).

i)        
Map modules.

j)        
Map Group domain specialization modules. 

k)       Delayed
Resolution domain specialization modules.

l)        
xNAL domain specialization modules.

m)     Basic
Ditabase document type shell (topic type, no domains).

n)       ditaval
document type.

 

2)       Technical Content Package

 

a)       DITA 1.2
Technical Content Specializations Architecture and Language 

Reference (concept, task, reference, glossary).

b)       DITA 1.2
Software Specializations Architecture and Language 

Reference (software, programming, and UI domains).

 

c)       Topic
document type shell (topic plus core topic domains plus the

software, programming, and UI domains).

d)       Concept
document type shell (concept plus core topic domains plus

the software, programming, and UI domains).

e)       Glossary
document type shell (glossentry plus core topic domains plus

the software, programming, and UI domains).

f)        
Reference document type shell (reference plus core topic domains plus

the software, programming, and UI domains).

g)       Task
document type shell (constrained task plus core topic domains plus the

software, programming, and UI domains).

h)       Concept,
glossary, reference, and task specialization modules.

i)        
Software, programming, and UI domain specialization modules.

j)        
Map document type shell (map plus map group, and indexing domains).

k)       Technical
Content Ditabase doctype shell (topic, concept, glossentry,

reference, task plus the core topic domains plus the software, 

programming, and UI domains).

 

3)       Book Specializations Package

 

a)       DITA 1.2
Book Specialization Architecture and Language Reference (bookmap).

 

b)       Bookmap
document type shell (bookmap plus map group, indexing,

and xNAL domains).

c)       Bookmap
specialization modules.

 

4)       Learning and Training Content Specializations Package

 

a)      
DITA 1.2 Learning and Training Content
Specializations Architecture and Language Reference.

 

b)      
Doctype shells for all of the Learning and Training
topic specializations except learningBase,

includes the core topic, software,
programming, UI, Learning topic, and Learning Metadata domains.

c)      
Learning and Training topic, map, and metadata domains.

d)      
Learning and Training map doctype shell (map plus the
Learning Map, 

Learning Metadata, and Learning topic
domains).

e)      
Learning and Training
bookmap doctype shell (bookmap plus the Learning Map and Learning Metadata
domains).

f)        
Learning and Training map domain specialization.

g)      
Learning and Training Ditabase doctype shell (all of
the Learning and Training topics,

plus topic, concept, glossary, reference, task, plus the core topic, software, programming, UI, Learning topic, and Learning Metadata
domains).

 

5)       Machine Industry Specializations Package

 

a)       DITA 1.2
Machine Industry Specializations Architecture and Language Reference.

 

b)       Machine
Industry Task doctype shell (task plus the core topic and

Machine Industry domain specializations).

c)       Machine
Industry domain specialization modules.

d)       Machine
Industry Ditabase doctype shell (topic, concept, reference, Machine Industry
Task,

plus core topic and Machine Industry domain specializations).

 

6)       Semantic Linking, Controlled Values, and Taxonomies

 

a)       DITA 1.2
Semantic Linking, Controlled Values, and Taxonomies Specializations

Architecture and Language Reference.

 

b)       Subject Schema
Map document type shell.

c)       Subject
Schema Map modules.

d)       Classification
Map document type shell.

e)       Classification
domain specialization modules.

 

7)       Combined Package

 

a)       All of the
above in one combined package.

 

 

Questions:

 

I.                    
Should the Learning and Training topics and ditabase doctype shells
include the software, ui, and programming domains?  John thinks they should, but will check with the
subcommittee.

 

II.                  
Do we want a Learning and Training map doctype shell that is based on
bookmap?  John says yes.

 

III.                 
Is it nuts to include so many variations of Ditabase doctype shells? Do
we want a ditabase in each package? Should we leave this up to the sub-committees?

 

IV.               
Should we include the approved Best Practice documents as an informative
part of the core package? Should we combine the existing best practice
documents into a single document?

 

V.                 
Which map document type shells should include the Delayed Resolution
domain? Basic map? Technical Content Map? Bookmap? Leaning Map?

 

VI.               
We have a constrained task doctype shell as part of the Technical
Content Package. Do we need to include an unconstrained task?  If so, in
which package?  Or is the Machine Industry Task an unconstrained task that
can serve this role?

 

VII.              
Notice that the Delayed Resolution domain is included in the core
package, that it is not included in any doctype shells.  Is this OK?

 

VIII.            
Notice that the xNAL domain is included in the core
package, but it is only included in the Bookmap doctype shell.

 

IX.                
There was a suggestion
that we have an additional package that would contain the combined
documentation and none of the DTD, XSD, and related files. This is not included
in the above proposal, but could be if members of the TC think it would be
useful.

 

X.                  
We will include the DITA
source, PDF, and chunked HTML output. Do we want to include HTML Help (chm) and
unchunked HTML output as well?

 

XI.                
Are seven or eight
packages too many (six individual, one combined, and possibly a combined
documentation package)?

 

XII.               
Questions about how to
coordinate Robert’s proposed changes to the organization of the DITA
Language Reference documents with the packaging proposal were raised during the
8 April DITA TC call.

 

XIII.             
There is a question about
the name for what is labeled the “core” package above.  Is “core”
OK or would “base”, “common”, or something else be
better.

 

XIV.            
There are questions about
the right place to put the xNAL and Hazard Statement domains that we need to
sort out.

 

XV.             
Is Technical Content a
good name for item #2 above?  Would Technical Publications be better? Something
else?