DITA 1.2 packages [updated yet again]

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

 

Only one packaging question left to
resolve on next week’s DITA TC call. I’ll send out a short note
about that question later.  This note just summarizes the decisions we’ve
made so far.

 

Comments and suggestions by e-mail to the list or directly
to me (), Robert (),
and Michael () are still welcome.

 

Resolved 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.  Need to get confirmation back from the sub-committee.

 

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 Base
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 Base 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 Base 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 Base package, and to create
separate xNAL directories for DTDs and XSDs within the Base package.

 

[This is where this morning’s DITA TC
discussion started.] 

 

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 will
have a separate combined documentation package and it will be the place that
holds 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 will include PDF output
for the documents in each of the packages and we will include the DITA source, PDF,
unchunked html, chunked html, and HTML Help output in the documentation
package. Don will work with Mary on
the details of OASIS approval and picking one of the outputs, probably PDF, as
the official output type to be approved with the other outputs provided as
non-normative conveniences.

 

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

 

No one
objected, in fact there were a few suggestions (not acted upon) for even more
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.

 

No one else
was really sure what the specific issue was or if there was one.  We’ll
sort things out as we go if necessary.

 

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.

 

Base
rather than core it will be.

 

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

 

We will put the xNAL
and Hazard Statement domains in the Base
package 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 below?  Would Technical Publications be
better? Something else?

 

This is
the question that we didn’t fully resolve.  We agreed that “Technical
Content” isn’t a particularly good name. We didn’t come up
with another name that everyone liked better. We agreed to keep thinking, to
post suggestions for better names to the list, and to revisit this question
during next weeks call.

 

As part
of the same discussion there was a call for creating a new package that would
be a lot like this package, but which would omit the software, programming, and
UI domains from the various document type shells. There wasn’t agreement
to do this. We did agree to keep the discussion open.

 

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

 

We didn’t
deal with this issue. The suggestion was to assume a package organization like
the one described below and for Don to work with Mary or others in OASIS to put
together a proposal for what exactly would be approved through the formal OASIS
process.

 

General comments:

 

 
We will organize the
     DITA 1.2 specification into a set of eight packages, 

     six individual packages, a combined
     documentation package, and 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 combined documentation and the combined package,
     individual packages 

     won’t duplicate the content from other packages.

 
The Base
     Package can be used by itself. 

 
Each of the individual non-Base packages requires the Base package and may

     require other packages.

 
The Base
     Package plus the Technical Content Package (by whatever name we end up 

     selecting) 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 something that Don 

     sorts out with OASIS. One suggestion was that the TC and OASIS approve the
     

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

 

1)       Base Package

 

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

metadata markup, processing including delayed resolution, 

specialization including constraints).

b)       DITA 1.2 Base 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 (or more
likely some better name that the TC picks) 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 Base
topic domains plus the

software, programming, and UI domains).

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

the software, programming, and UI domains).

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

the software, programming, and UI domains).

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

the software, programming, and UI domains).

g)       Task
document type shell (constrained task plus Base 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 Base
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 Base 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 

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