Support DITA input files #2

This product brief outlines the implementation of DITA support in Doc Detective, enabling technical writers to validate DITA-based documentation through automated testing. The implementation includes support for inline test statements, detected tests based on DITA's semantic structure, and processing of DITA map files.

Background

DITA (Darwin Information Typing Architecture) is an XML-based architecture for authoring, producing, and delivering technical information. As a structured documentation format widely used in enterprise environments, DITA organizes content into reusable topics, assembled through maps. Doc Detective currently supports testing Markdown, AsciiDoc, and HTML/XML formats, but lacks native DITA support.

Implementation Details

1. Add a new file type configuration to support DITA files. Should support the following extensions: .dita, .ditamap, .xml

2. Should support both XML comment-based and DITA specialization-based inline test and step statements. The specialization will need a formal DTD and schema to integrate with existing DITA toolchains.

3. To detect steps, the default file type definition's markup will map DITA elements to their closest equivalent steps. For example, <uicontrol> and <menucascade> can map to one or more find steps.

4. Implement support for DITA map files (.ditamap):

   • Process map files to identify all referenced topics
   • Follow topic references recursively
   • Create a unified test specification from all topics
   • Support topic filtering using DITAVAL conditions
   • Honor relationship tables for testing related content

5. Integrate dita-ot to process .ditamap outputs and generate content to test. May need to build a plugin to properly handle transforming content into tests.

Implementation Phases

1. Phase 1: Basic DITA support with XML comment-based inline tests
2. Phase 2: DITA map processing and topic reference resolution
3. Phase 3: DITA specialization for native test integration
4. Phase 4: Advanced features (conditional processing, keyref resolution)

Technical Requirements

• XML parsing capabilities with namespace support
• DITA DTD/Schema understanding for validation
• Topic reference resolution engine
• Integration with existing DITA publishing workflows

Benefits

• Seamless Integration: Works within existing DITA workflows without disruption
• Structured Testing: Leverages DITA's semantic structure for meaningful tests
• Reusability: Test definitions can be reused alongside DITA content
• Enterprise-Ready: Supports the complex document structures used in enterprise environments
• Automated Validation: Reduces manual QA efforts for DITA-based documentation

Conclusion

Adding DITA support to Doc Detective brings automated testing capabilities to enterprise documentation teams using structured content. By leveraging DITA's semantic markup and implementing specialized test elements, Doc Detective can validate complex documentation systems at scale while integrating with existing DITA toolchains.