Re: [dita] some comemnts on the Draft DITA 1.2 architecture spec.

[Eliot Kimber <ekimber@reallysi.com>]

On 7/1/09 11:33 AM, "Dana Spradley" <dana.spradley@oracle.com> wrote:

> 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.

I agree with Dana's characterization of the different activities as shown
below (must,should,may).

However, I'm not sure I agree that "customization" is the right word to
classifity all of these activities: DITA, by its nature, is a framework for
building concrete DITA-based applications. Any non-trivial use of DITA would
be customization, by this definition, because you can't actually use DITA
(safely) without at least creating local shells. But really creating shells
and constraints is configuration, in the way that many enterprises
distinguish between configuration (adjusting the features used or
controlling behavior through non-programming means), rather than
customization in the sense of modifying or extending the processing
implementation.

One can even argue that the creation of specialization modules is, by
itself, configuration since it doesn't, necessarily require any modification
to existing processing to be useful (that being one of the points of
specialization, after all).

However, I will concede that defining a specialized vocabulary is an
implementation action where defining shells and constraints is not (that is,
shell definition and constraint specification could both be enabled through
relatively simple UIs that remove the need for DTD or schema syntax
knowledge--that is not the case for specialization module implementation in
the general case [although there are many simple specialization use cases
where it could be enabled through a UI].
 
> 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 is a vendor implementation of DITA? It can only mean, in terms of the
standard, a DITA-aware tool that comes pre-packaged with at least the
standard vocabulary modules and some set of shell DTDs. No other aspect of
such a system is governed directly by the DITA standard, except to the
degree that the standard requires or suggests particular processing results.

It would make sense to talk about customizing such a tool's *processing*
(that is, it's particular implementation of DITA processing semantics) but
simply providing new shells or conforming vocabulary modules would not, I
think, be "customization" because doing so should not necessarily require
any modification to processing.

That is, as indicated in Dana's list below, support for shells, constraints,
and specialization modules is mandatory and the use of then should not
constitute "customization" by itself. Certainly the creation of shells and
constraints is very much a "configuration" activity, not a customization
activity, because it serves only to use or not use existing things.

Creating a specialized vocabulary could be seen as "customization" in the
sense that you may be creating new stuff to meet specific local
requirements, but because the ability to do so is a fundamental aspect of
DITA, it is much more simply "using DITA" rather than "customizing DITA"
(because DITA, itself is not a thing that you customize, but a framework by
which you create custom things).

In particular, I want very much for the act of using and creating
non-standard vocabulary modules to be presented as part of the normal use of
DITA, not something that takes you outside the normal parameters of DITA
use. Labeling it as "customization" seems to do that.

Cheers,

E.

 
> 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.:
>   a.. Shells: Vendors MUST support, implementors SHOULD use
>   b.. Constraints: Vendors MUST support, implementors SHOULD use
>   c.. Specialization: Vendors MUST support, implementors MAY use
>   d.. 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.
> 
>      
> 
>      

----
Eliot Kimber | Senior Solutions Architect | Really Strategies, Inc.
email:  ekimber@reallysi.com <mailto:ekimber@reallysi.com>
office: 610.631.6770 | cell: 512.554.9368
2570 Boulevard of the Generals | Suite 213 | Audubon, PA 19403
www.reallysi.com <http://www.reallysi.com>  | http://blog.reallysi.com
<http://blog.reallysi.com> | www.rsuitecms.com <http://www.rsuitecms.com>