[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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
Member of
the DITA Technical Committee
Chairman
of the DITA Machine Industry
Subcommittee Von: JoAnn Hackos [mailto:joann.hackos@comtech-serv.com] Gesendet: Dienstag, 29. April 2008 00:14 An: Ogden, Jeff; dita@lists.oasis-open.org 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 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]