[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
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>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]