RE: [dita] Re: Strawman Draft of General Conformance Specification

["Ogden, Jeff" <jogden@ptc.com>]

Some comments below.

 

   -Jeff

 

---

From: Deborah_Pickett@moldflow.com [mailto:Deborah_Pickett@moldflow.com]
Sent: Wednesday, March 05, 2008 2:15 AM
To: dita@lists.oasis-open.org
Subject: [dita] Re: Strawman Draft of General Conformance Specification

 

> The document named Strawman Draft of General Conformance Specification
> (conformance_1_2_wek.html) has been submitted by Don Day to the OASIS
> Darwin Information Typing Architecture (DITA) TC document repository.

My comments:

I see some implementations that are self-proclaimed to be DITA-conformant, but have extremely poor support for maps.  As a one-time user of such software, I would have appreciated knowing this ahead of time.  I would like to have some kind of conformance statement that the creators of the software can't weasel out of.  I don't know if the right approach is to list Required modules, or Required shells. If modules, perhaps each module lists the things that it Requires, so an implementation can be map-conformant but not bookmap-conformant.  I don't know if or where such a statement should appear in the conformance section.

 

At the end of the day I think the test for what is a conforming DITA-aware processor is can it use, create, or modify conforming DITA documents using conforming DITA document types and does the result also conform. I think we are limited to defining what is or isn’t conforming in order to ensure interoperability. I don’t see how we can go beyond this to use the DITA specification to tell implementers what features they need to support beyond a minimum sub-set required to provide interoperability. We can tell implementers what the required results are, but we can’t tell them how to achieve those results. We certainly can’t define what is or isn’t considered good or poor support.

 

What I think we can do is require implementers that claim to be DITA conforming to state (i) which features they have implemented (or if it is easier, which features they haven’t implemented), (ii) that they have implemented all of the features that are REQUIRED for a particular category of implementation, (iii) that all features that are included are implemented according to the requirements given in the DITA specifications, and (iv) what version of the DITA specification is implemented.

 

Will that do enough of what you are after?  

I would be upset if a DITA editor could read my specialized documents only by generalizing them back to topic (especially if it did not respecialize them on save).  At the moment I don't see any rules that forbid that.

 

I don’t think that this is something that should be or really can be forbidden by the DITA specifications.  It seems more like something that would cause you and most everyone else to choose a different editor.

I think the statement about specialization-awareness needs to be strengthened.  If a DITA editor ("topic-conformant") has extra features that it can apply to tasks, then I want to be confident that those extra features are inheritable by my own specializations of task.  I don't know how best to word this, but it's essentially about holding implementations to the spirit of specialization, and not just catering to their Chosen Few doctype shells.  Commercial DITA editors are, in my experience, often guilty of this.

 

Again I don’t know how or even if we should require something like this in the face of all possible “extra” features. I think we can encourage more full disclosure, so that people know what they are and aren’t getting.

The conformance requirements of information management systems seem to be so lax that a file system would almost pass the test.  Without additional statements on individual DITA features (e.g., "an href must refer to an existing DITA document, and the fragment, if any, must match an ID in that document") I can see this being abused by generic XML databases and other things that don't deserve the DITA stamp of approval.

 

I think this will be somewhat better when detailed conformance retirement information is added throughout the DITA specification.

 

I think there is a distinction between a DITA-aware Information Management System and an Information Management System that can be used with DITA, but which is not DITA-aware. At some point this comes down to what features are and are not implemented by a processor.

Is there a category for processors which convert stuff *to* conforming DITA documents?  This would apply to tools like doxygen, which produces machine-generated documentation of software APIs from comments in the source.  doxygen doesn't do DITA, but oh if it could...

There isn’t such a category now.  We could add one or we could expand the existing source to source transformer category to include non-DITA to DITA source transformers.  I guess the question we need to answer is are there going to be any requirements that are specific to the non-DITA to DITA transformers or will the same requirements apply as apply for DITA to DITA source transformers?

 

I'm quite happy with the rest of the document.

--
Deborah Pickett
Information Architect, Moldflow Pty Ltd, Melbourne
Deborah_Pickett@moldflow.com