Re: [dita] Test Environment for SC Business

[Eliot Kimber <ekimber@reallysi.com>]

Park Seth wrote:
> Hello DITA Technical Committee.
> 
> The Semiconductor Information Design Subcommittee (SIDSC) has released
> two drafts of the "sidsc-component" specialization, which addresses a
> very important information type to semiconductor businesses, tool
> vendors, and other service providers.
> 
> We are struggling to get adequate testing support of the specialization
> from all SC members. All member companies are active in the requirements
> analysis. However, most of the SC are not yet DITA users; many are not
> XML users. As such, only a few participants have a working DITA OT
> environment. Most are not able to ensure that their diligent analysis
> has been properly implemented (or that the analysis is correct, for that
> matter).
> 
> We want to make sure that we are serving the needs of the industry and
> that we've sufficiently exercised our work before we submit it to the
> TC.
> 
> What are our options for providing an accessible testing environment for
> these valued members?

In testing the specializations I create for clients, I create the 
following components:

1. Working declarations, including representative shell DTDs that 
include all the relevant domains and reflect all the important 
combinations of domains if not all domains are intended to be used with 
all topic types (which is normally the case if you have domains at all).

As part of these working declarations I include at least one trivial 
test document under the same directory as the module/shell it tests. I 
use the Arbortext organization convention of one directory per distinct 
module or shell (e.g., map shell, topic shell, topic module, map module, 
or domain module), e.g.:

doctypes/mytopictype/mytopictype.dtd
                     /mytopictype.mod
                     /test/mytopictype-test-01.xml

2. Formal usage and reference documentation for the specialized elements 
(I use my own variation of the elementref specialization--SC's would 
presumably use the same specialization used for the DITA standard).

3. A set of more complete sample documents that reflect either real data 
the specializations are intended to model or more complete test cases 
that cover a range of combinations and edge cases (ideally the realistic 
data also exercises your edge cases). I store these separate from the 
declarations since they are essentially system tests of declarations and 
supporting code.

4. Extensions to the Toolkit's HTML transform as needed to implement any 
specialization-specific HTML formatting, organized as a Toolkit plug-in 
(meaning at a minimum that the files can live in a directory under demo/ 
and make relative references to core components--it doesn't have to be a 
full plug-in in its own right).

5. Extensions to the PDF2 plug-in to implement any 
specialization-specific print formatting. This can also be organized as 
code in a directory under demo/.

5. Minimal setups for common editors (Arbortext Editor, Syntext Serna, 
XMetal, Oxygen) to enable graphical editing using the specializations. 
For Arbortext, Serna, and Oxygen this is pretty trivial to set up, at 
least without doing any specialization-specific styling. For XMetal I 
don't know as I haven't tried to configure the latest version.

6. Ant tasks and batch and shell scripts to run the HTML and PDF2 
transforms using the specialization-specific support.

Given these components it would be possible for anyone to download the 
package, perform a couple of simple one-time setup actions (adding some 
catalog entries, setting a few editor preferences) and then be able to 
use the specializations in realistic ways.

I don't know what, if any, facilities OASIS provides for code 
management, but I would that think whoever is maintaining the 
specialization declarations for a given SC could put this sort of 
package together without too much difficulty (I can provide a sample Ant 
script that automates the distribution packaging) and make that 
available from the TC's files area.

If the SC will require more involved processing (e.g., the Instructional 
Design SC) I think it would be appropriate to have an SC-specific 
plug-in managed under the Toolkit project on SourceForge.

Certainly if the above materials are made available for a given SC I 
will make a point of exercising them myself.

It seems like it would be useful to have a "SC support package template" 
that provides a starting point for putting together the above for a 
given SC.

Cheers,

Eliot
-- 
Eliot Kimber
Senior Solutions Architect
"Bringing Strategy, Content, and Technology Together"
Main: 610.631.6770
www.reallysi.com
www.rsuitecms.com