I share the concern that things are getting complex.
(On the other hand, DITA is complex, and not all of that complexity can be
spirited away.)
What goes into the OT isn't a question
for this OASIS TC. OASIS has nothing to do with the OT and it
shouldn't. The OT is just one implementation, and it is not under the
aegis of OASIS. If something is important/useful enough to be available
for any DITA user, it should be a product of this TC. If it is not a
product of this TC, it is just a private customization, not part of
DITA.
I don't know how to solve the problem of the complexity of
our many packages, but punting to the OT is not the
solution.
paul
From: SeicoDyne DITA
[mailto:]
Sent: Tuesday, 2008 April 29
4:32
To: 'JoAnn Hackos'; Ogden, Jeff;
Subject: 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.
