[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [dita] DITA 1.2 packages [an alternative proposal]
Hi everyone, Pardon the interruption, but I’m not sure what all
the discussion is about. The TC is creating a specification that will be
distributed in its entirety – anything not included isn’t part of
the specification; there are no “partial” deliverables. Beyond
that, if some other group of individuals (such as the DITA Toolkit developers)
find it useful to deliver only portions of the specification, that is up to
them with the caveat that they include links to the full specification set. It sounds like it might be useful for the Adoption folks
to create an install guide or a best practice or similar document that would
explain how to best configure the specification download for particular
applications, and of course the vendors are free to package their
implementations as they wish – separate from the TC. Now back to your regularly scheduled programming. Regards, Mary From: Ogden, Jeff
[mailto:jogden@ptc.com] Here
is a more detailed version of the alternative packaging proposal. I
encourage the TC to discuss the proposals and make some decisions over the next
week or two even thought I’ll be on vacation and unable to participate in
the discussion. You may want to start the discussion with the less
detailed version that I sent out this morning (a copy is included below) since
that is less dense and may be easier to discuss. In any case here is the
more detailed version: 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. The files and directories in the
packages will 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. For
DITA 1.2 we will create and distribute six packages: Full, Documentation,
Modular Content, Software, Learning and Training Content, and Machine Industry. Drop
the Core, Book, and the Semantic Linking, Controlled Values, and Taxonomies
packages that were included in the original proposal. 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 and the
Book package contents will be included in several of the individual packages. This
alternative, beyond the repackaging and the addition of the new 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. The
following “core” items are not a separate package, but are included
by all of a) DITA 1.2 Core
Architectural Specification (introduction, topic, map, and b) DITA 1.2 Core
Language Reference (map, topic, metadata including c) DITA 1.2 Utility
Domain Specializations Architecture and Language d) DITA 1.2 xNAL Domain
Specializations Architecture and Language Reference. e) Topic type modules. f) Topic domain
specialization modules for the indexing, utilities, g) Map modules. h) Map Group domain
specialization modules. i) Delayed Resolution
domain specialization modules. j) xNAL domain
specialization modules. k) ditaval document
type. The
packages will include: Full Package Includes everything, documentation, DTDs,
XSDs, and related files. In addition a) Subject Schema Map
document type shell (need details here). b) Subject Schema Map
modules. c) Classification Map
document type shell (need details here). d) Classification domain
specialization modules. e) Basic Topic document
type shell (topic type, no domains). f)
Basic
Map document type shell (only map type plus the map group domain). Documentation Package Includes all of the documentation including
DITA source, all outputs, a) The DITA source plus
chunked HTML, unchunked HTML, and b) The source and all
outputs for the DITA 1.2 Semantic Linking, c) The source and all
outputs for all of the approved Best Practice d) The source and all
outputs for the DITA 1.2 Processing Guidelines Modular Content Package (may want 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. Specifically: a) The core items, plus: b) DITA 1.2 Modular
Content Architecture and Language Reference (concept, task, reference,
glossary). c) DITA 1.2 Book
Architecture and Language Reference (bookmap). d) Topic document type
shell (topic plus core topic domains). e) Concept document type
shell (concept plus core topic domains). f) Glossary document
type shell (glossentry plus core topic domains). g) Reference document
type shell (reference plus core topic domains). h) Task document type
shell (constrained task plus core topic domains). i) concept, glossary,
reference, and task specialization modules. j) Software,
programming, and UI domain specialization modules. k) Map document type
shell (map plus map group, delayed resolution, and indexing domains). l) Bookmap document type
shell (bookmap plus map group, indexing, delayed resolution, and xNAL domains). m) Bookmap specialization modules. n) Modular Content
Ditabase doctype shell (topic, concept, glossentry, reference, constrained task
plus the core topic 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. Specifically: a) The core items, plus: b) DITA 1.2 Modular
Content Architecture and Language c) DITA 1.2 Software,
Programming, and User Interface Domains d) DITA 1.2 Book
Architecture and Language Reference (bookmap). e) Topic document type
shell (topic plus core topic domains plus the f)
Concept
document type shell (concept plus core topic domains plus g) Glossary document
type shell (glossentry plus core topic domains plus h) Reference document
type shell (reference plus core topic domains plus i)
Task document
type shell (constrained task plus core topic domains plus the j)
concept,
glossary, reference, and task specialization modules. k) Software,
programming, and UI domain specialization modules. l)
Map
document type shell (map plus map group, delayed resolution, and indexing
domains). m) Bookmap document type
shell (bookmap plus map group, indexing, n) Bookmap
specialization modules. o) Software Content
Ditabase doctype shell (topic, concept, glossentry, Learning and Training Content Package This would be the same as what
was proposed previously. Specifically: a) The core items, plus: b) DITA 1.2 Learning and
Training Content Architecture and Language Reference. c) Doctype shells for
all of the Learning and Training topic d) Learning and Training
topic, map, and metadata domains. e) Learning and Training
map doctype shell (map plus the map group, f)
Learning
and Training bookmap doctype shell (bookmap plus the g) Learning and Training
map domain specialization modules. Machine Industry Package This would be the same as what
was proposed previously. Specifically: a) The core items, plus: b) DITA 1.2 Machine
Industry Architecture and Language Reference. c) Machine Industry Task
doctype shell (constrained task plus the d) Machine Industry
domain specialization modules. General
comments:
From: SeicoDyne DITA
[mailto:dita@seicodyne.ch] 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:jogden@ptc.com] 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, 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 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:joann.hackos@comtech-serv.com] 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 www.comtech-serv.com From: Ogden, Jeff
[mailto:jogden@ptc.com] Any thoughts on the following? > In the packaging proposal there are (at least) three separate,
but related things being discussed: > 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 -Jeff From: Ogden, Jeff 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:joann.hackos@comtech-serv.com] 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 www.comtech-serv.com From: Ogden, Jeff
[mailto:jogden@ptc.com] 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 (jogden@ptc.com),
Robert (robander@us.ibm.com),
and Michael (mpriestlo@ca.ibm.com)
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:
1) Core Package a) DITA 1.2 Core
Architectural Specification (introduction, topic, map, and b) DITA 1.2 Core
Language Reference (map, topic, metadata including c) DITA 1.2 Utility
Domain Specializations Architecture and Language 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, 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 b) DITA 1.2 Software, Programming, and User Interface Domains c) Topic document type
shell (topic plus core topic domains plus the d) Concept document type
shell (concept plus core topic domains plus e) Glossary document
type shell (glossentry plus core topic domains plus f) Reference document
type shell (reference plus core topic domains plus g) Task document type
shell (constrained task plus core topic domains plus the 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, 3) Book Package a) DITA 1.2 Book
Architecture and Language Reference (bookmap). b) Bookmap document type
shell (bookmap plus map group, indexing, 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 c) Learning and Training
topic, map, and metadata domains. d) Learning and Training
map doctype shell (map plus the map group, e) Learning and Training
bookmap doctype shell (bookmap plus the 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 c) Machine Industry
domain specialization modules. 6) Semantic Linking,
Controlled Values, and Taxonomies Package a) DITA 1.2 Semantic
Linking, Controlled Values, and Taxonomies 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 b)
The source and all outputs for all of the approved Best Practice 8) Combined Package a) All of the above in
one combined package. |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]