There are several related issues here that we need to separate
out in our discussions:
1.
What is the folder/file structure and what names do we use when
we distribute the DITA DTDs and XSDs?
2.
What Public identifiers and what URIs do we use to reference the
various components?
3.
What doctype shells do we distribute, what domains do they
include, and what topic nesting do they allow?
4.
How may packages (.zip files) do we create and what goes in each
one?
5.
How is the written DITA 1.2 specification organized?
I think, but am not completely sure, that our recent discussion
of glossaries (and concept, task, and reference) has been about item #4
(packages). Can someone confirm that?
We did talk about all of this quite a bit many months ago, we
finally came to a consensus, and voted to accept a solution back then. At
that time there was a feeling on the part of some that DITA was perceived as
being very “techdocs” oriented and creating separate packages, including
the Technical Content “package”, was one way to address that and to
give other collections of specializations more visibility. At that time there
was also the concern that Michael reminded us about that DITA was already quite
large and was getting larger and that we needed to organize things in a fashion
that managed that complexity.
For me items #1 and #2 are much more important to than #3 and #4.
I think we’ve got the folder/file structure, names, Public identifiers,
and URIs in pretty good shape now, so I hope we don’t make any changes to
#1 and #2 at this point. I’m more open to changes to #3 and #4,
although this late in the DITA 1.2 cycle I guess I’m somewhat in favor of
limiting changes as much as we can. I really don’t think that there is
any single solution to #3 and #4 that will meet everyone’s needs and so I
expect that we will revisit the question of what is included in #3 and #4 at
fairly regular intervals well into the future.
As far as #4 (packages) goes, right now I think we are taking
the approach that there isn’t any overlap or duplication between the
packages except for the “everything package”. That means that
unless you are using the everything package or just need the base package, you
will need to combine two or more packages. We could take a different
approach to packaging and allow duplication and overlap between packages, so that
each package would be complete and self-contained. That would allow us to
include glossary (and concept, task, reference) in several packages, but
allow us to keep the folder/file structure as it is with a fairly small
collection of things in the “base” folder. We would still need to
figure out what is and what isn’t included in each package, but to the
extent that we have a sub-committee for each package, we might be able to ask
them to tell us what needs to be included to make their packages most useful.
-Jeff
From: Kristen James Eberlein
[mailto:]
Sent: Friday, August 21, 2009 10:34 AM
To: DITA TC
Subject: Re: [dita] problem with packaging of glossaries
Two key issues:
Who do we anticipate being the potential users of
the base package?
Michael, I want you to look at the current
contents of the language reference material for both the base and
technical content version. Is this as you have been envisioning it?
Best,
Kris
Michael Priestley wrote:
The point of a
separate base package is to provide the bare minimum of DITA support - just
topic, map, basic utility domain.
So absolutely
everything else gets relegated out to another package - and since we've only
got two other packages, that means they either go into tech docs or learning
and training.
I'm fine with
renaming the tech doc package to something else, if it helps - even "key
specializations" if that would do the trick. But if we move any
specializations into the base package, we undermine the point of having it.
Michael
Priestley, Senior Technical Staff Member (STSM)
Lead IBM DITA Architect
http://dita.xml.org/blog/25
"JoAnn
Hackos" <>
08/20/2009
05:40 PM
To
"Bruce
Nevin \(bnevin\)" <>,
<>
cc
Subject
RE:
[dita] problem with packaging of glossaries
I am
in favor of Bruce’s second recommendation. What is the problem with
stating that concept, task, and reference are key specializations in the DITA
standard? Why should they be relegated to technical communication only? I just
don’t see the point of that.
Even
if there is a All DITA package, we’re not including information about
task, concept, and reference information types in the base architectural
specification, but only in the arch spec for technical communication.
I’ve
never been in favor of this split and would strongly prefer that we include
task, concept, reference, and glossary in the base architectural specification.
That would leave us with the machine industry specialization, which is, of
course, extremely relevant for many outside the machine industry, and the
various domains (software, ui, programming, machine industry, safety hazard).
Also bookmap. Why is bookmap considered relevant only for technical
communication. It’s probably less relevant there and more relevant for
DocBook aficionados.
Since
I’m writing the tech comm arch spec content and the topic content,
I’d be very happy to restore task, concept, reference, and glossary to
the base arch spec. I could include a statement that these may primarily relate
to product documentation although I really don’t think that’s true.
JoAnn
JoAnn Hackos PhD
President
Comtech Services, Inc.
Skype joannhackos
From: Bruce Nevin
(bnevin) [mailto:]
Sent: Thursday, August 20, 2009 11:24 AM
To:
Subject: [dita] problem with packaging of glossaries
This came up in the spec authoring meeting today.
The problem: <glossentry> is specialized from
<concept>. <task>, <concept>, and <reference> are in
the TechDocs package. This forces <glossentry> etc. to be restricted to
the TD package. But non-TechDocs folks need glossaries, and support for
them should be in the base.
Two solutions:
1.
Accept this. Present it as an unfortunate fait accompli for 1.2 --
if you want a glossary, you have to use the TD package (or specialize your
own).
2.
Move <task>, <concept>, and <reference> back into
the base, sans TD-specific domain specializations, and include those
specializations in the TD package. Present this as an interim step toward
simplified topics being developed by the BusDocs SC.
Comment? Action?
/Bruce
