AW: [dita] DITA 1.2 packages [updated again]

Yes indeed, it looks very complex and our goal should 
be to make DITA more attactive to many user groups.

 

At the discussion last week I hardly opposed against 
the idea to combine concept/reference/task and software/ui/programming into one 
package. As this would neither be a modular design focussed package 
nor a complete DITA 1.0/1.1 like package. I do not like the idea that we propose 
(outside of the software industry) to the user: "here are our DITA 
modules/packages, you just have to combind what you need and then you have to 
delete what you do not need". 

Either we should provide modularized package, which can 
be combined flexible, or we provide just a full package where the user have to 
delete what they do not need. But promoting the idea of "here are modularized 
packages, select what you need" but then not to keep that promise, is not such a 
good idea.

 

If we are looking from the convenience view, it is 
becomming highly difficult. As for most people "convenient" might be defined 
differently.

 

Due to that I would like to propose the 
following:

 

As the DITA 1.2 Oasis Standard, we should provide 
the combined (complete) package only.

 

But in the DITA-OT we should 
provide two sets:

(there will be better naming, I just had to give them 
names)

 

- dita-ot/dtd 
(containing the combined package, 
here a user can find the complete package as he used to find in the DITA 1.0 and 
DITA 1.1 OT)

 

- dita-ot/dtd-packages

(a folder comparable with the demo folder, containing 
additional helpfull content, convenient to intermediate and advanced 
users.

 

-- dita-ot/dtd-packages/dtd-welltried 

(containing the DITA 1.0 and DITA 1.1 like package, 
here a user can find all the topics and domains he used to find in DITA 1.0 and 
DITA 1.1. Not much new to learn)

 

-- dita-ot/dtd-packages/dtd-modules
(containing all 
our modularized packages:

/base

/bookmap

/learning

/machineIndustry (machineryTask, mitask 
domain)
/software (software, ui, programming domains)

/subjectScheme

/techncalContent (concept, reference, 
task)

/xnal

 

with 
the modularized package a user can select what he/she needs.

 

Best 
regards

 

Chris

 

SeicoDyne 
GmbH

Eichenstrasse 
16

CH-6015 
Reussbühl

Switzerland

Tel: +41 
41 534 66 97

Mob: +41 
78 790 66 97

Skype: seicodyne

 

www.seicodyne.com



 

Member of 
the DITA Technical Committee

Chairman 
of the DITA Machine Industry 
Subcommittee

 

Von: JoAnn Hackos 
[mailto:] 
Gesendet: Dienstag, 29. April 
2008 00:14
An: Ogden, Jeff; 

Betreff: 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.