OASIS DITA for Enterprise Business Documents Bus Docs

OASIS DITA for Enterprise Business Documents (Bus. Docs) sub-committee Overview of approaches and issues, for discussion by OASIS Darwin Information Typing Architecture (DITA) Technical Committee

Executive Summary Many organizations have already investigated DITA. Organizations are discouraged by: Barriers. Difficulty in finding solutions. “Does DITA meet Bus. Docs needs? ” Risk of increasing variety of (non-)valid DITA implementation following attempts at Bus. Docs. Urgent need for reliable and consistent guidance in Bus. Docs implementation using DITA.

Barriers to adoption Aggregated authoring Complexity In practical terms, how can multiple authors or input sources be accommodated within the DITA topic and map model? DITA topic constraints appear complex in contrast to 'free-form' content. A percentage of topic elements and attributes appear irrelevant for Bus. Doc authors. Some Po. Cs tried to address these barriers by specializations or 'loose' DITA.

Why aggregated authoring is important for Bus. Docs A Bus. Doc comprises many topics. Each topic might be created, changed, or owned by a different person, team, or source. Changes to a topic result from editing, or input from SMEs. A Bus. Doc does not just reassemble topics into an aggregated document. Conditional publication. Different formats. Topic selection or combination.

Aggregated authoring For Bus. Docs, there are two possible approaches: Single, valid DITA file, containing multiple topics. This is saved as a map and individual topics. Tools that 'integrate' topics into maps during authoring.

Creating an aggregated document Multiple 'recommended' approaches exist for getting started. Implied or anecdotal suggestions: Use <dita> as root element, aka “using ditabase”. Use <topic> as root element, and create other nested topics. Use <topic> as root element, but modify DTDs to allow ditabase functionality, aka “editing the shell DTDs”.

Ditabase (from Bus. Doc perspective) Pro No modifications to shell DTDs. No specializations to nest core topic types. Broad range of use cases. Meets all use cases with topic specialization. Con Title representation. 'Unnecessary' <dita> element may be confusing, although it is logical, since DITA is the standard.

Shell DTDs (from Bus. Doc perspective) Pro Supports all core DITA types. Encourages local copies of shell DTDs. Provides title at document root → aggregated document title. Con Modifying shell DTDs: Adds complexity Potentially confusing Using topic as a wrapper invalidates semantics of a topic.

Document metadata Problem The <dita> element: Does not allow specialization. Has no place to store document metadata or title. Possible conclusion: Use specialization to hold document-level metadata irrespective of <dita> or <topic> at root. For <dita> element, specialize <topic> to hold document metadata. For <topic> element, specialize to hold both document metadata (but not block content), and provide a wrapper.

Alternatively. . . Save the aggregated document as a topic and maps. Have the user edit the map to add the document level metadata. Advantages: More consistent with DITA architecture. Emphasizes that the aggregated document is not necessarily the delivered document. Because of conditional processing, audience, repurposing, etc. Helps introduce the idea of topics, without causing

Transformation model An aggregated document could use transforms to: 'Burst' the document into topics and a map. Reassemble topics into an aggregated document, using a map. Possible at various stages by: DITA tooling that transforms during load / save events. Explicit 'bursting' step during save, with corresponding integration during load, all distinct from the tooling.

Standalone map editing Contrast: standalone editing of aggregation map v. virtual editing of the map in an aggregated document. Alternatively, separate maps for aggregated document, publishing, etc. Map editing enables: Conditional and semantic aspects, structural changes, attributes, meta-structures such as topicgroups, . . . The expert / publishing / architectural requirements expected of Bus. Docs. Not required for simpler aggregated authoring, which

Discussion points Conflicting approaches exist with no definitive guidance. SC believes a single, well rationalized and documented approach is important. Need guidance from TC regarding: Ditabase or topic with edited Shell DTDs Specialization of topic to hold map content, as opposed to map persistence? Validation of the mapping of topic nodes to map nodes What approach and extent?