DITA 1.2 packages [updated again]

Here is another version of the DITA 1.2
packaging proposal updated based on comments and suggestions received during
today’s DITA TC call and subsequent e-mail to the DITA TC list. Changes from
the previous draft are highlighted in blue.

 

I’m sure this will be discussed
again on next week’s DITA TC call. And comments and suggestions by e-mail to
the list or directly to me (), Robert (),
and Michael () are welcome.

 

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

 

This issue is settled until we hear back from the LTC subcommittee.

 

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

 

This issue is settled, we just need to do the work.

 

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?

 

We
agreed to include just one ditabase as part of the Technical Content package. If
the Learning and Training Content or the Machine Industry sub-committees want
ditabases to be included as part of their packages, they can request that. We’ll
assume that we don’t want or need the additional ditabases for these two
packages unless someone speaks up.

 

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?

 

We
agreed to include the Best Practice documents in the documentation package as
individual documents.

 

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

 

We
agreed to include the Delayed Resolution domain in all map doctype shells
unless a sub-committee explicitly asks for the domain to be omitted for map
doctype shells included in their package. No explicit requests made yet, but
its early.

 

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

 

The
Technical Content package will include a constrained task doctype shell. The
Machine Industry package will include a differently constrained task doctype
shell. The DITA 1.2 release will not include a completely unconstrained task
doctype shell, but individuals and organizations are free to create one if they
wish.

 

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?

 

This is
OK.

 

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

 

We
agreed to separate out the documentation for the xNAL package into its own
Architecture and Language Reference document, to include this document and
other xNAL files in the core package, and to create separate xNAL directories for
DTDs and XSDs within the core package.

 

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.

 

We didn’t
get to this item during today’s discussion, but while discussing other
items the feeling seemed to be that we should have a separate combined
documentation package and this would be the place to put the Best Practice
documents together with all of the documents from the other packages.

 

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?

 

We didn’t
talk about this during today’s call, but I suggest that we include PDF
output for the documents in each of the packages and that we include the DITA
source, PDF, unchunked html, chunked html, and HTML Help output in the
documentation package.

 

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

 

We didn’t
talk about this during today’s call, but so far at least no one has
expressed concerns about the number of packages.

 

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.

 

I’m
no longer sure what the issue was here. Robert is going forward to implement (a
prototype) of his suggested approach. I suggest that we came back and revisit
this after that work is done.

 

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.

 

We didn’t
talk about this during today’s call. In a e-mail exchange with Robert and
Michael I said I didn’t like “common” since we already have
common files (common to topics and map) and so having a package named common
might lead to “common common files” which would be confusing. 
I think we are going with “core” for now.  If someone has
strong feelings about this, they should speak up and hopefully offer
suggestions for a new/better name.

 

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

 

We
talked about this indirectly.  We seem to be leaning toward putting the
xNAL and Hazard Statement domains in the core package, but with a separate
document to describe xNAL. The xNAL domain will be used from the bookmap
doctype shell.  The Hazard Statement domain will be used from several
doctype shells in several packages.

 

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

 

The view
was expressed that Technical Content isn’t a good name. No suggestions
for an alternative so far.  Not sure if Technical Publications or TechPubs
is better or not. Probably not. We’ll probably stick with Technical
Content until someone suggests an alternative.

 

XVI.            
Not sure we have
agreement on item xii below.

 

 

General comments:

 

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

     packages plus a documentation
     package plus a 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 PDF output
     for the documentation specific to that package. The 

     documentation package includes DITA source, PDF, chunked HTML 

     output, and HTML Help (chm) and unchunked HTML output. The combined
     package 

     includes everything.

 
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
     documentation and 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, the Delayed
     Resolution 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 including
delayed resolution, 

specialization including constraints).

b)       DITA 1.2
Core Language Reference (map, topic, metadata including 

delayed resolution, map group domain).

c)       DITA 1.2
Utility Domain Specializations Architecture and Language 

Reference (utilities, highlighting, and hazard statement domains).

c.1) DITA 1.2 xNAL Domain Specializations Architecture and Language
Reference.

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.

n)       ditaval
document type.

 

2)       Technical Content Package

 

a)       DITA 1.2
Technical Content Architecture and Language 

Reference (concept, task, reference, glossary).

b)       DITA 1.2
Software, Programming, and User
Interface Domains 

Specializations Architecture and Language Reference.

 

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, delayed resolution, and indexing domains).

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

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

programming, and UI domains).

 

3)       Book Package

 

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

 

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

delayed resolution, and
xNAL domains).

c)       Bookmap
specialization modules.

 

4)       Learning and Training Content Package

 

a)       DITA 1.2
Learning and Training Content 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 map group, 

delayed resolution, Learning Map, 

Learning Metadata, and Learning topic domains).

e)       Learning and
Training bookmap doctype shell (bookmap plus the 

map group, delayed resolution,
Learning Map and Learning 

Metadata domains).

f)        
Learning and Training map domain specialization modules.

 

5)       Machine Industry Package

 

a)       DITA 1.2 Machine
Industry Architecture and Language Reference.

 

b)       Machine
Industry Task doctype shell (constrained task plus the 

core topic and Machine Industry domain specializations).

c)       Machine
Industry domain specialization modules.

 

6)       Semantic Linking, Controlled Values, and Taxonomies Package

 

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

Architecture and Language Reference.

 

b)       Subject
Schema Map document type shell (need
details here).

c)       Subject
Schema Map modules.

d)       Classification
Map document type shell (need details
here).

e)       Classification
domain specialization modules.

 

7)       Documentation Package

 

a)       The DITA source plus PDF, chunked HTML, unchunked HTML, and 

HTML Help output for all of the Architecture, Language Reference, 

Guideline, and Example documents from the other packages.

b)   The source and all outputs for all of the approved
Best Practice 

documents as individual documents.

 

8)       Combined Package

 

a)       All of the
above in one combined package.