AW: [dita] DITA 1.2 packages [an alternative proposal]

Unfortuneatly my dad died yesterday and I can not 
attend on the meeting today.

 

Jeff, 
I fully support your proposal. 

My 
concern was to have concept, reference, task and the software domains in one 
singel package only. Your proposal looks very convenient to me and thank you for 
your work.

 

Best 
regards and have a good meeting.

 

Chris

 

Von: Ogden, Jeff [mailto:] 

Gesendet: Dienstag, 6. Mai 2008 15:11
An: 

Betreff: RE: [dita] DITA 1.2 packages [an 
alternative proposal]

In an attempt to 
address the concerns that have been raised by Chris and JoAnn as well as one 
expressed privately by Erik and my own concerns about the number of packages, 
I’d like to put forward the following alternative packaging proposal for 
discussion today.

 

I suggest that we 
abandon the idea of having separate individual packages that do not duplicate 
the content of other individual packages and instead have several separate 
packages each of which is complete and self-contained. That the files and 
directories in the packages be structured and named so that several packages can 
be installed into the same directory with the duplicate files overwriting each 
other and producing a consistent result.

 

That for DITA 1.2 we 
create and distribute the following packages:

 

Full 
Package

     
Includes everything including documentation, dtds, xsds, and related 
files.

 

Documentation 
Package

    
Includes all of the documentation including DITA source, all outputs, 

      but no dtds, xsds, or related 
files

 

Modular 
Content Package (I’m open to suggestions for a better name)

    This 
would be what was the technical content package, plus bookmap,

    but 
without the sw-d, pr-d, and ui-d domains

 

Software 
Package

    This 
would be what was the technical content package, plus bookmap,

    but 
with the sw-d, pr-d, and ui-d domains included.

 

Learning 
and Training Content Package

   This would 
be the same as what was proposed previously.

 

Machine 
Industry Package

   This would 
be the same as what was proposed previously.

 

We would drop the Core, 
Book, and the Semantic Linking, Controlled Values, and Taxonomies packages. To 
get all of that content you would need to use the Full Package, although much of 
the abandoned Core Package content will be included in each of the remaining 
packages.

 

This alternative, 
beyond the repackaging and the addition of the Modular Content doctype shells, 
maintains the decisions that the TC previously made as far as splitting up the 
documentation and the overall structure of directories and 
files.

 

This alternative gets 
us down to 6 packages from 8.  Users don’t need to worry about dependencies 
between packages. Most users will be able to load just one package. The Software 
Package is very similar to what was included in DITA 1.1.  Even with the 
reduced number of packages, because of the addition of the Modular Content 
Package, we are offering a richer set of pre-packaged doctype shells. We’ve 
provided a less software oriented alternative. And we’ve given the software 
package a more honest name.

 

     
-Jeff

 

 

From: Ogden, 
Jeff 
Sent: Monday, May 05, 
2008 11:50 AM
To: 
''
Subject: RE: [dita] DITA 1.2 packages 
[updated again]

 

I’m not sure that a 
detailed description of the sort you are looking for is doable without knowing 
more about what applications the user is using (OpenTool Kit, XMetal, Arbortext, 
…) and what it is they are trying to do (what DITA doctypes they are using, what 
it is they need to adjust).  If someone can write down a specific use case 
or two, I’d be willing to try to address that.

 

A goal of the proposed 
packages is to provide one out-of-the-box doctype shell that includes everything 
that was included in DITA 1.1 in a DITA 1.1 doctype shell. In fact the proposed 
doctype shells generally provide a bit more than was included in DITA 1.1, but 
they don’t include everything that is new to DITA 1.2 in each doctype shell. 
 Thus some of the Machine Industry work isn’t available everywhere, but is 
only available in the Machine Industry package. And the Learning and Training 
Content specializations are available in the Learning and Training Content 
package.

 

Reading between the 
lines of your response it sounds as if you are more concerned about what is 
included in the doctype shells that are included in the out-of-the-box release 
from OASIS (item ii from my note) then you are about how many packages we have 
or what is included in which package (item iii) or about the division of the 
specification into smaller documents (item i).

 

   
-Jeff

 

From: JoAnn 
Hackos [mailto:] 
Sent: Monday, May 05, 2008 11:01 
AM
To: Ogden, Jeff; 

Subject: RE: [dita] DITA 1.2 packages 
[updated again]

 

Hi 
Jeff,

I guess what I’d like 
to understand in depth is the user experience with all of this. Is it possible 
to describe what will happen if someone gets a set that he or she needs to 
adjust, i.e., add one of the domains back in?

 

A clear explanation of 
the user experience would help us decide if the packaging is a benefit or a 
detriment.

 

Thanks for your 
continued thoughts on this.

Best,

JoAnn

 

JoAnn T. Hackos, 
PhD
President
Comtech Services, 
Inc.
710 Kipling Street, 
Suite 400
Denver, CO 
80215
303-232-7586

joannhackos 
Skype

www.comtech-serv.com

From: Ogden, 
Jeff [mailto:] 
Sent: Monday, May 05, 2008 8:33 
AM
To: 

Subject: RE: [dita] DITA 1.2 packages 
[updated again]

 

Any thoughts on the 
following?

 

> In the packaging 
proposal there are (at least) three separate, but related things being 
discussed:
>    (i)                   
There is the division 
of the documentation into a number of smaller subsets.  

>    (ii)                 
There is the structure 
of the directories that will hold the DTDs, XSDs, and related files.  

>    (iii)                
And there is the 
packaging of all of that into a collection of individual zip archives plus two 

>                
combined zip archives (documentation and everything).  

>

> Is it one 
particular item that is causing concern or is it all of them?

> 

> And, if it is item 
iii (the number of packages) that is causing concern, would moving from 8 to 3 

> or 4 packages help or do we need to get back to just a single package 
to resolve the concern?

 

   
-Jeff

 

From: Ogden, 
Jeff 
Sent: Tuesday, April 29, 
2008 9:29 AM
To: 
''
Subject: RE: [dita] DITA 1.2 packages 
[updated again]

 

In the packaging 
proposal there are (at least) three separate, but related things being 
discussed:

(i)                   
There is the division 
of the documentation into a number of smaller subsets.  

(ii)                 
There is the structure 
of the directories that will hold the DTDs, XSDs, and related files.  

(iii)                
And there is the 
packaging of all of that into a collection of individual zip archives plus two 
combined zip archives (documentation and everything).  

Is it one particular 
item that is causing concern or is it all of them?

 

And, if it is item iii 
(the number of packages) that is causing concern, would moving from 8 to 3 or 4 
packages help or do we need to get back to just a single package to resolve the 
concern?

 

JoAnn 
asked:

> 
Does the new packaging 
not require a significantly increased level of expertise to begin than we have 
had before?

 

My own feeling is that 
there should be no more expertise needed with DITA 1.2 than with DITA 1.1 to 
achieve the same level of functionality that someone had with DITA 1.1 because 
we plan to deliver out-of-the-box document type shells that are very similar to 
the doctype shells that were included in DITA 1.1. Where the additional 
expertise comes in is if someone wants to customize their use of DITA in ways 
that weren’t pre-packaged.  But that isn’t really anything new.  And 
someone can avoid having to make any choices by using the combined package that 
contains everything and not doing any customization.

 

DITA 1.2 does offer a 
number of enhancements that will require more expertise to use, but these are 
largely optional. One goal of splitting up the documentation and providing 
different packages was to allow users without the expertise or desire to use the 
new features to avoid having to deal with them. Not sure we have achieved that, 
but it was one of the goals.

 

JoAnn also 
asked:

> 
What packages are the 
editor and CMS vendors going to provide to their customers? How will they 
implement any or all of them? Aren’t we increasing the cost of entry and 
discouraging newcomers by making the choices too complex?

 

Hopefully the editor 
and CMS vendors have enough expertise to make good choices.  I think what 
we write into the DITA 1.2 Spec. as REQUIRED will have an impact on this, but 
that is something separate from packaging.  I’d hope that the packaging 
wouldn’t drive decisions on the part of the vendors.  Vendors are of course 
free to come up with their own packaging that may or may not be directly related 
to the OASIS convenience packaging as long as they correctly implement all of 
the REQUIRED portions.

 

    
-Jeff

 

 

From: JoAnn 
Hackos [mailto:] 
Sent: Monday, April 28, 2008 6:14 
PM
To: Ogden, Jeff; 

Subject: RE: [dita] DITA 1.2 packages 
[updated again]

 

Well, I do think we 
have too many packages – all of these make the decisions for new users even more 
confusing than just downloading one package. It won’t be clear to newcomers what 
they’re getting or not getting if they aren’t already experts and/or 
consultants. What packages are the editor and CMS vendors going to provide to 
their customers? How will they implement any or all of them? Aren’t we 
increasing the cost of entry and discouraging newcomers by making the choices 
too complex?

 

Committee members 
casually talk about creating new local shells but most of the people I know who 
are implementing DITA aren’t capable of doing any of that. Does the new 
packaging not require a significantly increased level of expertise to begin than 
we have had before? 

 

If this packaging was 
intended to make adoption easier, I feel we’ve gotten far away from that goal. 
We’re making adoption more complex instead.

 

JoAnn

 

JoAnn T. Hackos, 
PhD
President
Comtech Services, 
Inc.
710 Kipling Street, 
Suite 400
Denver, CO 
80215
303-232-7586

joannhackos 
Skype

www.comtech-serv.com

From: Ogden, 
Jeff [mailto:] 
Sent: Tuesday, April 15, 2008 3:58 
PM
To: 

Subject: [dita] 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.