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

[Dana Spradley <dana.spradley@oracle.com>]

I'm inclined to agree Eliot.

Systematically written conformance clauses that distinguish between the levels of conformance required by various conformance targets, and that assign REQUIRED keywords to normative statements that support those features that are most likely to be used by installations, and OPTIONAL keywords to normative statements that support features that are least likely to be used, would go a long way toward making DITA a more precise and flexible standard than our current conformance language does.

But we don't want this exercise to get out of hand and seriously delay delivery of 1.2, do we?

We need to keep it within bounds, I think.

-----Original Message-----
From: Eliot Kimber [mailto:ekimber@reallysi.com]
Sent: Monday, July 06, 2009 9:50 AM
To: Dana Spradley; Ogden, Jeff; dita
Subject: Re: [dita] some comemnts on the Draft DITA 1.2 architecture
spec.


I feel very strongly that we need to have a real conformance clause in the
spec--without such a clause, it's not a standard.

Also, I believe OASIS rules now require us to have a conformance clause. I'm
willing to take responsibility for that part of the spec.

Cheers,

E.

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

> thanks Jeff - I was coming up to speed on the OASIS conformance guidelines -
> http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html -
> just before reading this, and in that context it makes a lot of sense
> 
> you're right - a lot of work would needed to be done to get conformance in
> order in the 1.2 spec - sorry to hear not much has been done to progress your
> draft of last March
> 
> at this point, perhaps it is best to concentrate on regularizing our
> conformance clauses to use the standard upper-case vocabulary for 1.2, and
> work on integrating something along the more robust lines of your draft for
> 1.3
> 
> an issue I have with our vocabulary as it exists in the draft so far, besides
> its non-standard nature, is that it tends of be overweighted toward the
> REQUIRED end of the spectrum for features that  are designed to support
> round-trip generalization and re-specialization, and conrefs between
> differently constrained document instances - which not every implementation
> wants or needs to support - and gives less play to the RECOMMENDED and MAY
> parts of the spectrum, especially for these advanced kinds of features
> 
> also, I think the specifications needs a statement at the end that at least
> recognizes the validity of creating non-conforming DITA variants that are only
> based on the specification, but derive their interoperability from generic XML
> standards alone - the way, e.g., that the DocBook standard does
>   -----Original Message-----
>   From: Ogden, Jeff [mailto:jogden@ptc.com]
>   Sent: Thursday, July 02, 2009 1:09 PM
>   To: dita
>   Subject: RE: [dita] some comemnts on the Draft DITA 1.2 architecture spec.
> 
> 
>   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/conforman
> ce1.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:dana.spradley@oracle.com]
>   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: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.:
> 
>       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> 


---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail.  Follow this link to all your TCs in OASIS at:
https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php