-----Original Message-----
From: Ogden, Jeff [mailto:jogden@ptc.com]
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:dana.spradley@oracle.com]
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:jogden@ptc.com]
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:joann.hackos@comtech-serv.com]
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.
joann.hackos@comtech-serv.com
Skype joannhackos
From: Dana Spradley
[mailto:dana.spradley@oracle.com]
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:jogden@ptc.com]
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.