And a slightly different take on this issue.
Dana wrote:
> I'm not
sure why we shouldn't distinguish between vendors, implementers, and authors in
the spec.
You could, but you’d have
to do it very carefully. And so far the DITA spec. hasn’t done much of
this, so it will be a lot of new work and probably take a lot of discussion to
get agreement.
If you distinguish between people or organizations that have
different roles in examples and other non-normative descriptions, it isn’t
too hard to do. If you start to try to impose different requirements on
different people or organizations, then things get a lot more complex very
quickly.
The draft conformance statement that was originally written by
Eliot and revised by me back in March 2008 starts to address these issues, but
there hasn’t been much done with this since then. See:
http://www.oasis-open.org/apps/org/workgroup/dita/download.php/27616/conformance1.2-jcoV2.pdf
The thing to note in the draft
conformance statement is that rather than talking about people and
organizations with different roles (vendors, implementers, authors, …) it
talks about implementations and the “requirements that must be met for
documents, document types, specialization modules, and processors to be
considered DITA conforming”.
Different levels of conformance
are allowed for different types of implementation and a DITA conforming
implementation does not have to implement all features to be conforming. Some excerpts
from the draft conformance statement:
·
DITA conforming implementations MUST include a conformance
statement that lists the DITA features that are supported by the implementation
and are implemented in accordance with the requirements of the DITA
specifications ….
·
Documents, document types, specialization modules, and processors
that implement the requirements given in the OASIS approved DITA specifications
are considered conforming.
·
Implementations that include some DITA features, but not others,
are considered conforming as long as all REQUIRED features for the category of
implementation are included and all of the features that are included follow
the requirements given in the DITA specification. An implementation which does
not include a particular optional feature MUST be prepared to interoperate with
another implementation which does include the feature, though perhaps with reduced
functionality. And, while less common, an implementation which does include a particular
optional feature MUST be prepared to interoperate with another implementation which
does not include the feature.
·
Organizations and individuals are free to impose additional
constraints on their own use of DITA that go beyond the requirements imposed by
the DITA specifications, possibly including enforcement of the constraints by
their local tools, as long as the result continues to meet the requirements given
in the DITA specifications. For example, a given user community could impose
rules on how files must be named or organized even if those rules go beyond the
requirements given in the DITA specifications.
The draft statement goes on to
define five Conformance Categories:
1. Required
and invariant
2. Required
but variable
3. Variable
with defaults
4. Variable
without defaults
5. Informative
or non-normative
As well as five types of
processors:
1. DITA-Aware
Processor
2. DITA
Editor
3. Information
management system
4. Renderer
5. Source-to-source
Transformer
And then seven feature groups:
1. Documents
(required, but variable)
2. Document
types (required, but variable)
3. Specialization
Modules (required, but variable)
4. Addressing
(required and invariant)
5. Linking
(required, but variable)
6. Content
reference (required and invariant)
7. Rendition
behavior (variable with or without defaults)
The work that I don’t
think has been done is to define a more detailed list of DITA features, to
state if each feature is required or optional, and place each feature into one
of the feature groups listed above or possibly in new feature groups, if none
of the existing groups works well for a particular feature.
All of this is done without
talking about vendors, implementers, or authors (people, organizations, or
roles). Instead the people or organizations would identify what it is
they have implemented, what type of implementation it is, what features the implementation
includes, that all required features for the type of implementation have been
included, and that all of the requirements for all included features have been
met. Once all of that is done, they are entitled to claim that they have
a “DITA conforming” implementation.
Or at least that was the
thinking from more than a year ago.
The DITA TC will need to decide
how much or how little of this they want to take on for the DITA 1.2
specification. To do this completely and well will be a lot of work.
-Jeff
From: Dana Spradley
[mailto:]
Sent: Wednesday, July 01, 2009 5:59 PM
To: Ogden, Jeff; dita
Subject: RE: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.
Hi Jeff--
I'm not sure why we shouldn't distinguish between vendors,
implementors, and authors in the spec.
The HTML spec, for example, distinguishes between authors, users,
and user agents, and imposes different kinds and levels of conformance on each.
Also, I think most tools that support DITA also support XML in
general - which allows for much greater customizability even than DITA.
So typically if an implementor diverges from the DITA standard, but
conforms to more generic XML standards, their vendor toolkit will support them.
For example, the authoring/publishing tool I'm most familiar with
has implemented DITA conrefs...but generically, so that any xml application can
use them - and call the attribute that supports them by any name it wants to.
So it seems vendors are already going beyond the call of duty to
support customers who want to implement standard DITA features, but in various
non-standard ways.
Shouldn't the standard indicate where we acknowledge the validity
of such divergence - and encourage vendors to support it - and where we
absolutely don't - and mandate that vendors do not support it?
--Dana
-----Original Message-----
From: Ogden, Jeff [mailto:]
Sent: Wednesday, July 01, 2009 10:55 AM
To: dita
Subject: RE: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.
Dana,
I think what you outline makes a
lot of sense. But the DITA specification doesn’t really make a
distinction between vendors, implementers, and end user authors. And I’m
not sure we should treat these classes of folks differently in the
specification. Requirements are requirements and should apply to everyone. We
shouldn’t have different requirements for vendors than we do for other
implementers or for authors.
What this all points out is that
one of DITA’s strong points is how customizable it is, but the fact that
it is so customizable makes it harder to write an understandable and
unambiguous standard. Although some might argue that using the words
“standard” and “understandable” in the same sentence is
a conflict to start with :-).
Another thing that makes this
hard is that the DITA TC only has the DITA Specification to work with or
perhaps the DITA Specification plus some best practice documents. If we had
something other than the DITA Specification such as an Implementer’s
Guide or a User’s Guide that might allow us to focus the specification on
true standards issues and focus the other documents on issues that are of more
concern to implanters or authors. I guess some of this might be something that
the DITA Adoption TC could take on, but it would be a lot of work and
isn’t likely to happen soon.
Given the recent discussions I
would update my outline to look something like this:
1) Customization
1.1) Specialization
1.1.1) Structural Specialization
1.1.2) Domain Specialization
1.2) Integration (via
document type shells)
1.2.1) Modules
1.2.2)
Constraints
1.3) Processing
1.3.1)
Transformations
1.3.1.1) Conditional Processing (filtering and flagging)
1.3.1.2) Conref processing
1.3.1.2) Merging properties between maps and topics including key and keyref
processing
1.3.1.3) Default attribute value processing
1.3.2) Stylesheet processing/formatting
But I would note that the use of
“customization” above is different from the definition of
customization in the DITA 1.1 spec. In the DITA 1.1 spec. it seems as if
customization, integration, and specialization are peer terms. If we want
to stick with that (we don’t have to), then we need a new word, perhaps
“configuration”, and the outline might look like this:
1) Configuration
1.1) Specialization
1.1.1) Structural Specialization
1.1.2) Domain Specialization
1.2) Integration (via
document type shells)
1.2.1) Modules
1.2.2)
Constraints
1.3) Processing
1.3.1)
Transformations
1.3.1.1) Conditional Processing (filtering and flagging)
1.3.1.2) Conref processing
1.3.1.2) Merging properties between maps and topics including key and keyref
processing
1.3.1.3) Default attribute value processing
1.3.2) Customization (stylesheet processing/formatting)
The items toward the top of the
outline are pretty tightly defined by the DITA specification. The items toward
the bottom of the outline are less tightly defined or in the case of (1.3.2)
Customization, perhaps undefined by the specification.
-Jeff
Here are the DITA 1.1
definitions:
Customization
When you just need a difference in output, you can
use DITA customization to override the default output without affecting
portability or interchange, and without involving specialization.
For example, if your readers are mostly
experienced users, you could concentrate on creating many summary tables, and
maximizing retrievability; or if you needed to create a brand presence, you
could customize the transforms to apply appropriate fonts and indent style, and
include some standard graphics and copyright links.
Use customization when you need new output, with
no change to the underlying semantics (you aren’t saying anything new or
meaningful about the content, only its display).
Integration
Each domain specialization or structural
specialization has its own design module. These modules can be combined to
create many different document types. The process of creating a new document
type from a specific combination of modules is called integration.
Integration is accomplished using a document type
shell, which defines the modules to be integrated and how they will be
integrated. Integration defines both what topic types and domains will be
allowed in the document type, and how the topic types will be allowed to nest.
The module for a specific type should contain only
the declarations for elements and attributes that are unique to that type, and
should not embed any other modules. The shell should contain no markup
declarations, and should directly reference all the modules it requires.
Nesting shells or nesting modules (having shells that embed other shells, or
modules that embed other modules) is discouraged since it adds complexity and
may break some tools. Sharing between document types should be accomplished
through shared modules, not through direct reference to any other document type.
Dependencies between modules should be satisfied by the integrating shell, not
through the module itself.
What is specialization?
Specialization allows you to define new kinds of
information (new structural types or new domains of information), while reusing
as much of existing design and code as possible, and minimizing or eliminating
the costs of interchange, migration, and maintenance.
Specialization is used when new structural types
or new domains are needed. DITA specialization can be used when you want to
make changes to your design for the sake of increased consistency or
descriptiveness or have extremely specific needs for output that cannot be
addressed using the current data model. Specialization is not recommended for
simply creating different output types as DITA documents may be transformed to
different outputs without resorting to specialization (see Customization).
There are two kinds of specialization hierarchy: one
for structural types (with topic or map at the root) and one for domains (with
elements in topic or map at their root, or the attributes props or base).
Structural types define topic or map structures, such as concept or task or
reference, which often apply across subject areas (for example, a user
interface task and a programming task may both consist of a series of steps).
Domains define markup for a particular information domain or subject area, such
as programming, or hardware. Each of them represent an “is a”
hierarchy, in object-oriented terms, with each structural type or domain being
a subclass of its parent. For example, a specialization of task is still a
task; and a specialization of the user interface domain is still part of the
user interface domain.
Use specialization when you are dealing with new
semantics (new, meaningful categories of information, either in the form of new
structural types or new domains). The new semantics can be encoded as part of a
specialization hierarchy, that allows them to be transformed back to more
general equivalents, and also ensures that the specialized content can be
processed by existing transforms.
From: Dana Spradley
[mailto:]
Sent: Wednesday, July 01, 2009 12:33 PM
To: Ogden, Jeff; JoAnn Hackos; dita
Subject: RE: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.
I think I'm starting to agree with you Jeff: the entire section
should be called "Customization," and specialization should be
considered a species of customization.
So the distinction is between using a vendor implementation of DITA
off the shelf and out of the box without modification - which some, perhaps
many implementors are going to do - and "customizing" that vendor
implementation to fit customer requirements.
What this section needs to do in terms of conformance is to spell
out vendor and implementor responsibilities for each kind of customization to
achieve an interoperable, or at least a harmless, system (to use the RFC
phraseology on conformance statements), i.e.:
Shells: Vendors MUST support, implementors SHOULD use
Constraints: Vendors MUST support, implementors SHOULD use
Specialization: Vendors MUST support, implementors MAY use
Variation (or whatever we call customization that changes some
parts of the DITA vocabulary or violates some of its architectural
principles, yet produces valid XML, and perhaps even valid DITA document
instances): Vendors SHOULD support, implementors MAY use
-----Original Message-----
From: Ogden, Jeff [mailto:]
Sent: Tuesday, June 30, 2009 11:23 AM
To: JoAnn Hackos; Dana Spradley; dita
Subject: RE: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.
I don’t know if there is a
less “drastic” and more appropriate term than “customization”,
but I’m sure that “specialization” isn’t the right word
to use when someone creates a new document type shell. Specializations
create new DITA types. Modifying a document type shell doesn’t create a
new DITA type, but just assembles existing DITA types for use. One of the
goals of the constraints proposal as I remember it was to allow customization
without requiring specialization.
I’ve always thought of
“specialization” as being a subset of the larger class of
customizations:
1) Customization
1.1) Specialization
1.1.1) Structural Specialization
1.1.2) Domain Specialization
1.2) Customized Document
type shells
1.3) Customized Processing
1.3.1)
Transformations
1.3.2)
Stylesheet processing/formatting
Part of the problem here may be
that we don’t have good names for 1.2 and 1.3.
-Jeff
From: JoAnn Hackos
[mailto:]
Sent: Tuesday, June 30, 2009 1:52 PM
To: Dana Spradley; Ogden, Jeff; dita
Subject: RE: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.
Should not we always refer to such changes as
“specializations” rather than “customizations”?
JoAnn Hackos PhD
President
Comtech Services, Inc.
Skype joannhackos
From: Dana Spradley
[mailto:]
Sent: Tuesday, June 30, 2009 11:46 AM
To: Ogden, Jeff; dita
Subject: RE: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.
Is "customized"/"customization" really
appropriate here? Are is this something we're considering less drastic than
customization?
-----Original Message-----
From: Ogden, Jeff [mailto:]
Sent: Monday, June 29, 2009 7:37 PM
To: dita
Subject: [dita] some comemnts on the Draft DITA 1.2 architecture spec.
Some
suggestions with additions underlined and blue
and deletions strikeout and red:
Concrete document types
A given DITA map or topic document is governed by a concrete
document type that defines the set of structural modules (topic or map types),
domain modules, and constraints modules that the map or topic can use, as
well as the degree of topic nesting that is allowed within the document type. While
the DITA specification includes a starter set of concrete document types for
common combinations of modules, those document types are not mandatory and, for
most many DITA users, include more things definitions than they
need for their documents. In general, any production use of DITA involves
definition of the DITA users are encouraged to create their own customized
concrete document types that include the set of modules best suited
to local requirements. This always customization
requires the creation of "local shell" document types,
even if all they do is omit unneeded modules or apply constraints to the
standard DITA-defined vocabulary. Thus you should expect in any
production use of DITA that the first step is to define local concrete document
types.
Note: The simplest form of local shell is an
unaltered copy of one of the DITA TC-provided shells to which is associated a
new public identifier or absolute URI, reflecting ownership
of the new shell by its creator. For example, to create a local shell DTD for
generic maps, simply copy the TC-provided file "map.dtd" to a local
location, possibly using a new name for the file to avoid confusion, and create
an entity mapping catalog that binds the new copy of map.dtd to a public ID or absolute URI you
define, e.g. PUBLIC "-//example.com/DTD DITA NewMap//EN or urn:public:example.dom/dita/doctypes/map
urn:example.com:names:dita:xsd:newmap.xsd.
Concrete DITA document types must SHOULD follow
the implementation design patterns defined in this specification. This ensures
consistency of implementation and also serves to make the task of creating
concrete document types almost entirely mechanical.
·
Modularization
and integration of design
Specialization hierarchies are implemented as sets of vocabulary modules, each
of which declares the markup and entities that are unique to a specialization.
The modules must be integrated into a document type before they can be used.
·
DTD
syntax specialization design patterns
To be extensible and backward compatible, DITA requires that a DTD
implementation of structural and domain specialization modules SHOULD conform
to well-defined the design
patterns used for the DTD shells included as part of the DITA
specification and described in this topic.
·
XSD
schema specialization design patterns
To be extensible and backward compatible, DITA requires that an XML
schema implementation of structural and domain specialization modules SHOULD conform
to well-defined the design patterns used
for the XML schema shells included as part fo the DITA specification and
described in this topic.
While we
can require that customized concrete document types follow the rules as
outlined in the DITA 1.2 speciication, I don’t think that we can require
that they follow the design patterns or that the design patterns are well
enough specified to allow them to be a requirement. At this stage I think
the design patters are more of a “best practice” than a requirement
that must be followed and so they SHOULD be followed rather than MUST be
followed.
It
seems likely that the section on “Modularization and integration of
design” should be deleted since it is almost entirely repeating
information that has been provided in the main section..
For the page dita-1.2-spec/arch/20090617/createConstraintsDomainSpec.html
:
I
don’t have any comments on the main topic other than to say that it feels
as of this topic is saying the same thing two or even three times and that
probably isn’t a good idea.
