OASIS DITA BusDocs Subcommittee€¦ · Web viewBackground Members of the DITA for Enterprise...

1OASIS DITA BusDocs Subcommittee Communiqué to the DITA Technical CommitteeAggregated Authoring of Topics and a Map

Background

Members of the DITA for Enterprise Business Documents (BusDocs) subcommittee have conducted a range of activities over the past two years that have included analyzing business document models, interacting with end-users to determine requirements, and implementing DITA in live projects for authoring of a broad range of non-technical document types. The following summarizes the subcommittee’s findings that are relevant to this subject:

Many of the characteristics that make DITA an ideal standard for technical documentation apply to other types of narrative documents created throughout an enterprise;

There is no widely adopted enterprise standard for authoring of XML business documents. As a result organizations must implement a number of standards-based or internally developed schemas

Numerous organizations have already looked to DITA as a potential solution for a single enterprise authoring schema. For example, the BusDocs subcommittee has encountered the following projects that range from proof-of-concept to full deployment:

Industry Application

Pharmaceutical Regulated drug application documents including protocols, study reports, and control documentation

Manufacturing Project reports, risk analyses, SoPs, contractsConsulting and Investment Research

Analyst reports

Cross Industry: Marketing

Key messaging documents, product brochures, datasheets

Central Government Legislative memoranda, policy statements, strategic plans

Divisional Government

Regulations

NGOs Strategic plans, situation analyses, annual reports

The organizations that we have encountered have been impressed both with the advantages offered by DITA and with a finite list of apparent incompatibilities between the DITA architectural standard and the generalized business document model. Two immediate issues raised by most organizations are:

o The need for aggregated authoring of a document consisting of a number of topics while still supporting the DITA topic and map storage model

o The perceived complexity of the DITA topic and apparent irrelevance of specific topic elements and attributes to the requirements of business document authors

July 28, 2010 of 24Draft for Internal Subcommittee Review


Many of these organizations have implemented proof of concept, pilot, or production projects that have attempted to reconcile these apparent incompatibilities using anything from valid specializations to very loose variations of DITA.

These projects have by necessity relied on secondary sources or internal analysis for guidance in the absence of a DITA TC recommended approach to the perceived issues.

The result of the current situation is that at best there are a wide variety of valid or non-valid DITA implementations that lack the type of consistency that supports tool growth and broad adoption. At worst, organizations attempting to resolve perceived issues on their own face discouragement and the possible conclusion that DITA does not meet the needs of enterprise business documents.The BusDocs subcommittee suggests that there is an urgent need to provide reliable and consistent guidance to support organizations in their efforts to implement DITA for business documents. Our research indicates that the current DITA 1.2 standard provides multiple approaches that meet the requirements of the generalized business document model without the need to request that changes be incorporated into the next release of DITA. Unless the approaches discussed are found to be deficient in ways that cannot be corrected by the Technical Committee within the DITA 1.2 standard, it would appear that the promotion of a recommended solution could be provided as soon as the Technical Committee was able to agree on the best approach. The core purpose of this communiqué is to promote some type of official guidance in the near future.

Relationship to Previous Subcommittee Work

Last year, subcommittee member Steve Manning authored and submitted the document Aggregated Authoring: Need and Functional Description, on behalf of the BusDocs subcommittee. The purpose of the document was to describe and clarify the need for aggregated authoring for tool vendors and other interested parties. The document was not intended to be prescriptive regarding technical approaches, but did acknowledge that, without modification to the DITA specification, there were two potential approaches:

Edit a number of topics within a single file using the current architecture that DITA provides for this purpose, with the ability to transform the aggregation to and from individual topics and a related map.

Acknowledge that some authoring tool vendors might support authoring against both the map and topic DTDs at the same time, using proprietary technology to expand the topics within map for authoring, while saving and loading individual topics and a related map.

In the time since the original aggregated authoring document was posted, the BusDocs subcommittee has had numerous discussions with other DITA technical committee members, DITA practitioners, and end users. The purpose of this document is to build on the knowledge gained in order to provide a “suggested implementation” based on the first approach described above which leverages the current DITA standard. While the subcommittee recognizes that tool vendors will always be able to provide proprietary solutions at will, we believe that offering an off-the-shelf recommendation based on the standard will allow the broadest tool support and simplest implementation of DITA for the widest possible range of enterprise business documents.

The subcommittee has incorporated excerpts from the Darwin Information Typing Architecture (DITA) Version 1.2 Committee Draft 03 dated 22 June 2010. Readers are encouraged to consult the current version of that document as the authoritative source for referenced content.



Audience and Purpose

This document has several potential audiences and associated purposes:

Audience Purpose

DITA Technical Committee members

The BusDocs subcommittee is requesting that the DITA Technical Committee vet the approaches discussed in this document and provide an “official” position to the business document community. We have discussed the approaches that seem obvious to us based on our understanding of the DITA standard and recognize that the Technical Committee may arrive at different conclusions. The subcommittee’s goal is to promote the rapid provision of a recommended approach, not necessarily one of the approaches that we have discussed.

DITA Practitioners A growing number of DITA practitioners have implemented a range of business document types with aggregated topics. Feedback regarding the approaches discussed in this document and comments are welcomed.

Tool Experts and Vendors To the best of our knowledge, the approach in this document can be implemented in a standard XML editor without requiring code changes or extensive configuration. Tool experts and vendors are asked to review the document to ensure that this goal has been met.

End-user Business and Technical Strategists

Strategists who are researching the correct approach to an enterprise authoring schema, or examining DITA’s applicability to enterprise business documents, are asked to provide feedback on document clarity and perceived strategic value of the approaches discussed.

In terms of technical expectations, we anticipate that all audiences are at least familiar with the basic terminology and architecture of the DITA standard. We suspect that potential adopters of this solution may have only a rudimentary understanding of DITA, and therefore we provide more information than would be required for Technical Committee members alone.



Introduction

The reader is encouraged to first read background information on DITA and the document Aggregated Authoring: Need and Functional Description, unless already well acquainted with DITA and the rationale behind the DITA BusDocs subcommittee.

For the purposes of this communiqué, the following simple definitions will be used:

Enterprise implies the activities of multi-department public, private, or not-for-profit organizations.

Enterprise business documents refer to the complete taxonomy of narrative documents created by knowledge workers within these organizations.

Narrative documents exclude those documents that would be better classified as “forms” or “tabular reports” that do not also contain significant amounts of narrative content.

Technical documentation is an example of a major branch within this enterprise taxonomy, and a vital part of the information exchange that organizations hope to gain when implementing DITA enterprise-wide. However, for the purpose of this document, the term business documents should be taken to exclude technical documentation, since we are focusing on a set of documents that has different characteristics.

The historical roots of this discussion are word processing documents that have normally consisted of a single file. If more than one file represented a complete document, it was for practical reasons that had nothing to do with the concepts of componentization, single sourcing, or other document approaches that are commonly associated with XML. The aggregated document is designed to provide users who are used to working on these types of word processing documents as authors, editors, or reviewers, a DITA document context that will be comfortable for them.

While there are a number of schemas available for business documents that provide aggregated authoring as their normal configuration, DITA brings unique benefits that are not as easily provided with other schemas. The goal of the BusDocs subcommittee is to provide aggregated authoring while still enabling the technical realization of DITA benefits that are assumed to be more achievable with single topic authoring. We would suggest that organizations will need to develop maturity models that reflect the added burden that aggregated authoring places on componentization, and the BusDocs subcommittee hopes to help do this. However it is not our goal to provide such a model in this document, or to defend a position that states organizations can have aggregated authoring and the benefits of topic authoring as well. Or goal is to provide the technical basis for this to occur, so that given a workable technical environment organizations can begin the process of developing their DITA oriented document processes.

BusDocs Subcommittee Scope

The broad appeal of DITA is reflected in the number of specific industry subcommittees that have already been formed, as well as those that many people expect will be added in the coming years. An extensive level of domain knowledge is required to properly discuss the



implementation of DITA in these various subcommittees. Existing subcommittee work illustrates that many of the issues discussed are specific to the goals and requirements of a particular subcommittee, without particular overlap across the subcommittees.

However, if we were to define a subset of issues that could be expected to affect many subcommittees, these issues would clearly not relate to specific domain requirements such as the need to harmonize DITA with SCORM, or to incorporate specific metadata that is required for documentation relating to semiconductors. The BusDocs subcommittee would suggest that the subset of common issues would often relate to a generalized document model that represents a broad range of business document types.

The BusDocs subcommittee views the analysis of the common structural and semantic elements of this document model as a primary activity of the subcommittee. Our hope is that the subcommittee ultimately fulfills a dual role:

As a resource to the technical committee providing domain expertise on the generalized requirements of business documents and the “common” understanding of the applicability of DITA to these requirements. The current and past subcommittee members are all focused on structured authoring of business documents as their primary concern.

As a reference point for the work of other subcommittees that removes the need for each subcommittee to individually address these issues that are common to generalized business document requirements. Based on the subcommittee’s understanding of our goals, we are concerned with a very broad range of documents across most public and commercial industry segments. However, the BusDocs subcommittee’s suggested involvement in these areas is limited to the generalized business document requirements that we view to be foundational issues that affect all business documents regardless of industry. Our concern is that failure to address these issues once with a global view will result in a variety of approaches being implemented in different subcommittees. This would be a waste of resources, a hindrance to interoperability, and a source of continual confusion to anyone who needs to implement the work of more than one of the growing number of business document oriented subcommittees.



Aggregated Topic Authoring

Working with a document that consists of multiple topics aggregated together represents one or more individual steps that can take place in the lifecycle of a document. There is a very well established “best practice” approach to document creation, review, approval, and revision that should be common to all readers. It is in the context of this document lifecycle that we will try to isolate the various activities that require a technical solution to be recommended.

The following diagrams and accompanying narrative describe the iterative document lifecycle that will discussed in this communiqué, beginning with the simplest case and then introducing the additional aspects of the process that add various complications.

Basic Aggregated Authoring

1. The creation of a new document that consists of a number of topics2. Saving of that document as individual topics and a map.3. Opening of the document by retrieving the map and aggregated the topics together.4. Saving of the document as new versions of the topics and the map.

Figure 1: Basic Aggregated Authoring

For the purpose of this discussion, aggregated authoring is defined by the full process pictured above, not just by the editing of multiple topics in a single document. To clarify, numerous organizations may find benefit by saving aggregated topics as a single file, but



the goal of this discussion is to allow organizations to go further by saving, and subsequently re-aggregating, individual topics and a map. This will provide organizations with the additional benefits of DITA such as the component authoring pictured in the following diagram which adds individual editing of topics before the second aggregated document session occurs. This is identified as Step 2.1 in the diagram, occurring before Step 3. Notice that Step 3 now creates the third revision of the topics, instead of the second revision as before.

Editing Individual Topics

2.1. One or more business authors edit the standalone topics creating new versions on save.

Figure 2: Aggregated Authoring with Individual Editing of Topics

This type of individual topic editing could be the result of various review processes or the need to have content created by a number of subject matter experts. This is a very good illustration of how many organizations may find themselves in between full single topic or aggregated authoring on the path of a maturity model that is continually evolving.

Creation of New Maps or Editing of Existing Map

A major benefit of aggregated authoring as discussed in this communiqué is the ability to leverage DITA maps for more than just the reassembly of the aggregated document. The following diagram illustrates that DITA maps can be used to:

publish the aggregated document conditionally, deliver it in various formats,



or select from and optionally combine the topics in the original aggregation with other topics

As pictured in the diagram, standalone map editing to include topics from an aggregated document can occur with the full functionality provided by DITA, and in a manner that is completely nonintrusive to the aggregated document.

2.2. Content Architect either retrieves map as a starting point, or creates new map from scratch

2.3. Content Architect saves as a new map, which is not a new version of the aggregated map

Figure 3: Standalone Creation of Derivative or New Maps Using Topics from Aggregated Document

Figure 3 identified the least intrusive manner in which a content architect can create a map to more robustly publish an aggregated document. We suspect that some organizations may see this as needless duplication and would prefer to edit the original map and save a new version as is depicted in Figure 4:

2.4. Content Architect saves a new version of the aggregated map



Figure 4: Potentially Complex Reconciliation of Standalone Map Editing and Aggregated Authoring

Reuse Individual Topics

To be completed

Summary: Need to discuss and if possible distinguish between conref of a topic, which is a purposeful reference, and reuse of a topic, which is the equivalent of adding the topic to the map in this “visual map” environment. The difference is that the first usage would result in a conref (either within a topic or within the map – to be discussed), whereas the second would result in an existing topic being added to the document and saved in the aggregated map with the same status of the other topics that are in the map.

Reuse Sections of an Aggregated Document

To be completed

Summary: First there is an issue of how the user would identify what section of a document was to be reused. The apparent logical approach would be to reference a node in the map that represents the document, although this could be implemented in many different ways in a UI.

There may be the same ambiguity that existed with reuse of a topic, but there is clearly a use case that represents the insertion of a child map into the existing map. What does this mean to the aggregated document, or to the map? In the aggregated document, the topics will appear similarly to the rest of the topics, unless again the intent of the author was to reference the “section.” It is possible to reference the topics as a child map in the map, but the following must be reconciled:



1. The actual child map did not exist at the time of its usage. The author pointed to a node in a map.

2. Does the force the creation of a child map? To do so might be a content management decision.

3. If a child map is forced, how does the child map persist in the aggregated document? The individual topics are to be inserted in the document and there must be something to identify that they do not belong to the map, but to a child map instead.

4. The alternative is to simple traverse the map node and add the topics to the document. They will ultimately be added to the aggregated map when the document is saved. This seems truer to the intent of the author, since the author was not intending to make a new object (the child map), the author was simply trying to reuse content in the document.

The following sections will examine the requirements, discussed approaches, and potential process impact for each of the steps described above.


Create New Aggregated Document

While the primary intent of this paper is to address the storage and subsequent editing of the aggregated document and its components, the first step is to create the aggregated document itself. Various blog posts and discussion threads have addressed the issue, however we were not able to find a recommended approach in either the new DITA 1.2 documentation or other TC deliverables. The recommendations that appear as blog posts and discussion threads follow three different, technically valid (if not equally beneficial) paths to implementation:

Use of <dita>as the root element of an aggregated document that allows the creation of any sequence of concept, task, and reference topics, with nesting of these topic types within each other. Throughout this discussion, this approach will be referred to as “using ditabase,” after the ditabase.dtd.

Use of <topic> or another topic type as the root element of an aggregated document that allows the creation of any number of topics of the same topic type as the root element with nesting of these topics within each other.

Use of <topic1> as the root element of an aggregated document with the additional modification of the DITA shell DTDs to allow the same functionality as is provided by the use of <ditabase> as the root element. Throughout this discussion, this approach will be referred to as “editing the shell DTDs.”

The BusDocs subcommittee requests that the Technical Committee issue some type of formal guidance that either recommends one of these approaches over the others, or provides an analysis of the relative advantages and disadvantages of each approach (as well as whether there are any alternative approaches that the subcommittee might have missed). Our own analysis has led to a perceived understanding of the reasoning behind the different approaches, as well a potential list of relative advantages. While we recognize that the Technical Committee may expand upon or even correct some of our discussion, we feel it is valuable to provide background for less technical readers and to help more technical readers understand our perspective as business document practitioners and users.

The basic DITA topic types allow nesting of topics within topics and therefore are capable of representing what we are calling an aggregated document. For this general nesting of topics within topics, DITA specifies two restrictions:

A topic nested within a topic must be of the same type. For example, concept can contain another concept and task can contain another task.

Nesting must occur after the close of the container topic body.

The DITA standard recognizes that there are cases where heterogeneous topic types need to be nested; and the ditabase definition (ditabase.dtd or ditabase.xsd) exists for this purpose. Ditabase allows <dita> to be used as the root element in place of a topic type, and in doing so expands the nesting capabilities of topic to include heterogeneous topic types. Ditabase does not remove the restriction that nesting must occur after the close of the topic body.

1 The subcommittee recognizes that any topic type could be used as the root element with the editing of the shell DTDs. This was not mentioned because our internet search only turned up a recommendation for <topic> and we were limiting the discussion to encountered recommendations.

The following provides additional detail on the additional flexibility provided by ditabase:

Ditabase allows topic, task, reference, glossentry, or glossgroup as peers in the root element:

Doctype Content model

ditabase ( topic or concept or task or reference or glossentry or glossgroup) (one or more2)

Example<dita> <concept id="a">...</concept> <task id="b">...</task> <task id="c">...</task> <task id="d">...</task></dita>

DITA 1.2 Language Reference: <dita> Element Content Model

This creates a document that at its first level of nesting can contain all topic types defined within ditabase. It can also accommodate all topic types at each subsequent level of nesting since it expands the topic content model to allow heterogeneous nesting: The following table shows the different content models for the concept topic type when used with a root element of <concept> or a root element of <dita>. Note that only these two cases are discussed because the restriction on heterogeneous nesting prohibits concept from being used with any of the other topic types as the root element.

Doctype Content model

Concept ( (title) then (titlealts) (optional) then (abstract or shortdesc) (optional) then (prolog) (optional) then (conbody) (optional) then (related-links) (optional) then

(concept) (any number) )

Ditabase ( (title) then (titlealts) (optional) then (abstract or shortdesc) (optional) then (prolog) (optional) then (conbody) (optional) then (related-links) (optional) then

(topic or concept or task or reference or glossentry or glossgroup) (any number) )

Expansion of the Concept Content Model within Ditabase

Example-<dita>

<concept id="concept"><title>Introduction to Bird Calling</title><conbody>

Bird calling requires learning:<ul>

<li>Popular and classical bird songs</li><li>How to whistle like a bird</li>

2 Source of this and similarly formatted content: Darwin Information Typing Architecture (DITA) Version 1.2 Committee Draft 03 dated 22 June 2010


http://www.oasis-open.org/committees/download.php/36200/dita1.2-complete.pdf

</ul></conbody><task>

<title>How to Whistle Like a Bird</title><taskbody>… </taskbody>

</task></concept>

</dita>3

DITA 1.2 Language Reference: <concept> Element Content ModelBold Text Highlights Expansion of Content Model under <dita>

Editing of the DITA Shell DTDs

It has been pointed out that a similar expansion of topic to allow for heterogeneous nesting of topic types can be achieved by editing the local copies of the DITA shell DTDs4. For the benefit of non-technical readers, this amounts to making legal and documented changes to the core definitions of DITA, such that topic becomes more flexible when used at the root of an aggregated document.

The following provides a preliminary summary of the relative merits of using ditabase or editing shell DTDs to allow heterogeneous nesting.

Approach Pro Con

ditabase Requires no

modification to shell DTDs or specialization to nest core DITA topic types

Meets a broader spectrum of use cases with the core DITA topic types

Meets all use cases with specialization of topic

Does not provide a way to represent the document title without using a topic for this purpose

Adds the seemingly unnecessary DITA element to the document which may confuse business authors

topic with modified shell DTD Supports all core DITA

topic types

Encourages local copies of the shell DTDs which is considered a “best practice” by some DITA technical committee members

Modifying the shell DTDs as a requirement of configurations for BusDocs adds complexity and potentially confusion for adopting organizations

Topic as a wrapper for an aggregated document

3 Adapted from: Darwin Information Typing Architecture (DITA) Version 1.2 Committee Draft 03 dated 22 June 2010

4 http://drmacros-xml-rants.blogspot.com/2009/05/why-dita-requires-topic-ids-and-why.html. Content that is relevant to this discussion begins approximately halfway through the post with the words “If you are using ditabase documents, stop.”


http://drmacros-xml-rants.blogspot.com/2009/05/why-dita-requires-topic-ids-and-why.html

Provides a title within topic at the root of the document which could be used as an aggregated document title

invalidates the semantics of “topic” which may lead to significant confusion on the part of business authors

The recommendation of one approach over the other is a decision that we expect to be vetted and determined at the Technical Committee level. As input to this process, the subcommittee would suggest that:

Ditabase allows aggregated authoring of a generalized business document model to be accomplished off-the-shelf with no modifications or specializations. As stated previously, we would prefer to not require a separate layer of modifications to achieve aggregated authoring when organizations will already need to specialize in order to meet business requirements of various document types.

Ditabase was originally designed to model legacy aggregated documents that contained heterogeneous topic types. Therefore the use of ditabase for BusDocs configurations is true to the original design of ditabase, if not the original purpose

Regarding the potential confusion to business authors that either <dita> or <topic> at the document root might cause, the BusDocs subcommittee suggests that:

o the use of an element at the root of the document that is not repeated elsewhere is less confusing,

o that business authors will view <dtia> as a natural root that represents the standard, regardless of whether they understand the elements technical purpose, and

o that the use of <topic> at the document root is counter to its semantic meaning and potentially very confusing

For the sake of simplicity, the remainder of this document will discuss aggregated authoring in the context of ditabase, with the understanding that the ultimate recommendation will be determined by the Technical Committee.

Saving the Aggregated Document as a Map and Related Topics

This discussion begins with a simple document example:

The aggregated document form of this document appears as:

<dita><topic id="topic 1">

<title>Topic 1</title><body>

This is the body of Topic 1</body><topic id="topic 1.1">

<title>Topic 1.1</title><body>

This is the body of Topic 1.1</body><topic id="topic 1.1.1"><title>Topic 1.1.1</title>

<body>This is the body of Topic 1.1.1

</body></topic>

</topic></topic>

</dita>

This document could be saved as a map and associated topics, assuming that each of these topics is saved with a filename that matches its title:

<map id="samplemap"><title>Aggregated Topics</title>

<topicref href="topic 1.dita" type="topic"><topicref href="topic 1.1.dita" type="topic">

<topicref href="topic 1.1.1.dita" type="topic" /></topicref>

</topicref></map>


This simple example provides a basis to discuss the more complete requirements for pairing an aggregated document with singly stored topics and an associated map. The approach must meet the following requirements:

1. The BusDocs Aggregated Authoring Solution must unambiguously identify map topicref and topichead elements in the aggregated document without requiring the author to edit attributes or map-specific elements

2. The BusDocs Aggregated Authoring Solution must allow the author to change a topichead to a topic or a topic to a topichead in the simplest manner possible

The following example illustrates a common structure encountered in business documents. The difference between this and the simple example provided above is that titles are nested directly in some cases without the inclusion of content between a parent title and a child title:

Table 1: Use Case Example of Mapping of Topic to Topicref and Topichead

Business Document Content Related Map Component

Determining Element

topicheadtopicheadtopicref

topicref

topicref

topicref

body/content

body/content

body/content

In the above example, Overview of Terms and Conditions of Award represents a topichead while Public Policy Requirements, which exists at the same level of heading in the authored document, represents a topicref. The clear difference between these is that one includes a body while the other does not, which naturally led to the idea that a topic containing a body could be mapped to topicref within a map while a topic that does not contain a body could be mapped to topichead. This fulfills the first requirement of an unambiguous mapping that does not rely on an author editing attributes.

Using the body element for this purpose also fulfills the second requirement of allowing the author to interchange topicref and topichead in a simple manner. Although this represents an element change in the map, for the aggregated document author it is a natural additional



or removal of content that exists under a “heading” in the document. This allows the author to:

1. Write the document without concern for how it represents map components. It is likely in these use cases that the author may not be aware that maps exist or that they contain structural distinctions such as topicref and topichead

2. Change any topic representation from or to a topicref or topichead by simply adding or deleting content. For example, as soon as a body is added to Overview and Terms and Conditions of Award, it would change the representation from a topichead to a topicref.

Creation of the Topics and Map

Based on the approach to aggregated authoring that is being discussed, the aggregated document itself will be a valid DITA document, unless it contains errors that are not related to the aggregation itself. The normal expectation would be that upon save the aggregated document would be stored in a single XML file. Regardless of what approach is taken to save as individual topics and a map, additional technology must be introduced in order to have these individual files logically created based on the content of the aggregated document.

We would suggest that a simple approach would be the use of XSLT for this purpose. As part of the BusDocs subcommittee work, we have experimented with XSLT transforms for both “bursting” the document as topics and a map, and use of the map to reassemble the topics into an aggregated document. We envision that these transforms can be implemented in multiple ways:

Close integration with DITA editing tools that are able to invoke transforms on load and save events

Loose integration as a step in the process of saving and loading an aggregated document if close integration with the editing tool is not possible

Integration as a step in the process of saving and retrieving the topics and map to and from a content management system

Depending on the final approach recommended by the Technical Committee, the work already done by the BusDocs subcommittee or work that we are will to do to provide these transforms may be relevant. We believe that the provision of transforms or other infrastructure required by the Technical Committee’s recommended approach will encourage adoption of the solution.

Virtual Editing of the Map

While the requirement is that business document authors not need to be aware of DITA maps, there is still a direct relationship between certain types of edits that take place in the aggregated document and associated changes that will appear in what we will call the aggregation map5 when it is saved. Any structural change to the aggregated document that adds, deletes, or moves a topic will result in a structural change to the aggregation map when it is saved.6

5 The ability to create multiple maps that incorporate the same topics is a characteristic of DITA. For the sake of clarity, we will refer to the map that is created when the aggregated document is saved as the aggregation map to distinguish it from other maps that may be created manually.

6 Depending on the final design recommended by the Technical Committee, other aggregated document edits could affect map content, if not structure. The examples in this document suggest a



We refer to this concept as virtual editing of the map, which occurs regardless of whether the person editing the aggregated document is aware of the map’s existence or not. This is not an important distinction if the map is only being used for the purpose of saving and then recreating the state of the aggregated document. However shortly we will consider standalone editing of the map by a user other than the aggregated document author, at which time it will be important to remember the aggregated document author’s role of “virtual map editor.”

Opening the Aggregated Document

We suggest that opening the aggregated document would consist of identifying the map, and then invoking a process that traverses the map, retrieves the topics, and assembles them into an instance of the aggregated document. Assuming that there have been no edits to either the topics or map since the previous aggregated authoring session, the previous and current aggregated documents are required to be identical.

As with the extraction of the topics and map from the aggregated document, XSLT could be used for the reassembly. We suspect that most implementers would want to mirror the integration approach that was adopted for the extraction, whether it be:

Close integration with DITA editing tools that are able to invoke transforms on load and save events

Loose integration as a step in the process of saving and loading an aggregated document if close integration with the editing tool is not possible

Integration as a step in the process of saving and retrieving the topics and map to and from a content management system

Is should be noted that depending upon how the assembly process is implemented, its use might not be limited to maps and topics that were originally created in an aggregated document. Conceivably any collection of topics could be assembled into an aggregated document using a map. We suspect that whether this broad aggregation capability is available to users will be decided by tool vendors and the implementing organizations.

We have encountered questions as to whether the aggregated document itself should be saved as the simplest approach to reassembling the topics for subsequent edit. This would be in addition to the individual topics and maps. Since standalone editing of the topics is a requirement, and standalone editing of the map is an open discussion item, there is no guarantee that the aggregated document, if saved, would represent the correct state of its content.

The BusDocs subcommittee would also be willing to contribute XSLT for the reassembly of the aggregated document.

relationship between the topic title and the topicref title in the map. If a similar approach is suggested by the Technical Committee, then a change to a topic title would result in a change to the content of the map.



Additional Processes

Standalone Editing of Topics

We have not identified any technical issues with standalone editing of the topics based on the approach being discussed. We do anticipate process issues that are inherent in standalone topic authoring and that can best be dealt with through education and the modeling of processes based on the current state of the organization as measured against a maturity model.

Creating a New Map that includes Aggregated Topics

We also have not identified any technical issues with creation of a new map that includes aggregated topics. Process issues appear to be those that are common with content reuse through maps.

Standalone Editing of the Map

When editing the aggregated document, the author may delete, insert, or move topics or topic trees.7 Based on the approach suggested by the BusDocs subcommittee, these actions directly impact the aggregation map, either deleting, inserting, or moving topicrefs or topicheads. The result is a very simple map that simply serves the purpose of persisting the structure of a single version of the aggregated document and contains no additional information to support publishing or other enterprise objectives.

Limiting the aggregation map to such a simplistic role removes the majority of functionality that DITA intends. However, just because the aggregated author is not expected to be a map expert, this does not mean someone will not fulfill this role in the organization. We expect that organizations that are serious about benefiting from DITA will invest in map expertise and want to apply this expertise to their aggregated document content. A user who fulfills this function may be referred to as a content architect, publishing expert, editor, or any number of other names. The aggregated document lifecycle we are discussing anticipates this role and refers to it as a content architect.

Expert editing of the aggregation map is able to provide the full scope of DITA conditional and semantic publishing capabilities to the organization. It also introduces a number of potential conflicts that could disrupt the business process, since with standalone editing the aggregation map will no longer a static object simply waiting to serve the purpose of reassembling the topics into an aggregated document. For example, the standalone editor may:

add, delete, or move topics add attributes to topicrefs or topicheads that need to be preserved through the next

aggregated authoring session add topicgroups or a number of other map elements that are not relevant to the

aggregated document author and nevertheless must be preserved as well

One way to avoid this conflict would be to eliminate all standalone editing of the aggregation map. Creating additional maps for publishing and other activities is consistent with DITA since the concept of multiple maps that incorporate the same topics is a cornerstone of the architecture. 7 Topics are nested within topics in the aggregated document. The result is a hierarchical tree structure

that is referred to here as a topic tree.



However, we suspect that simply suggesting this approach without explaining the issues that might occur if standalone editing of aggregation map occurs may frustrate the efforts of implementing organizations. We also anticipate that examining the many issues that standalone editing may introduce will help vet the suitability of our suggested approach when compared with other approaches that may seem to offer a more robust interoperability between standalone editing of the aggregation map and what we have called virtual editing of the same map in an aggregated document.

The static nature and single purpose of the map changes when standalone editing of the map is added to the process. The simplified use case is:

1. A business user creates an aggregated document which is saved as a map and associated topics.

2. A content architect edits and saves a new version of the map adding elements and attributes not expected to be exposed to authors of aggregated business documents.

3. The business user edits and saves the aggregated document without regard to the advanced map content added by the content architect.

The requirements surrounding this use case are: 1. Provision of as much native map functionality as possible for standalone map editing2. Aggregated authors must be as unencumbered as possible by the persistence of

structure required only for standalone editing of maps or topics3. The same level of version control and file locking for the aggregated map and topics

that would be provided by the implementation environment if the map and topics were edited standalone.

4. “Round-tripping” of a map between aggregated and standalone authoring while persisting all map content that is not purposely modified in either authoring session.

The requirement to persist map content after each aggregated authoring session is not fulfilled by the XSLT transforms discussed earlier

Persistence of Content from Standalone Map Editing

As expressed above, enterprise requirements will demand that the standalone map editor expose map features that are not required for aggregated authoring users. Since usability and simplicity is critical to the aggregated authoring audience, a basic premise of the aggregated authoring configuration is that the tag set must be as sparse as possible. This creates a conflict between the standalone map authoring requirements and the aggregated document authoring requirements.

The BusDocs subcommittee has been discussing this issue for some time and previously considered what may seem to be the most obvious approach, but one that we found did not meet all of the above requirements. This approach is covered here for the benefit of readers who may consider it the first choice and wonder why it has not been adopted.

The aggregation of topics within ditabase is lossless, since the content models for aggregated and standalone topics are the same. However, map and topic represent different structures with different purposes and the content model for map is substantially different than the content model of ditabase or topic. This leads to issue of how this additional map content could preserved through multiple iterations of standalone and aggregated authoring.



The first approach considered was to specialize topic to hold and persist the additional map content. This immediately led to a conflict with requirements to keep the aggregated authoring content model as simple as possible for non-technical business document authors. As a compromise, this approach suggests constraining map to only include the most necessary features needed by standalone map editors and thereby limiting the content that would need to be persisted in the aggregated document.

The result of this approach is that aggregated authors are exposed to some level of map content in the aggregated document and standalone map editors lose some level of map functionality. How much each of them is impacted by the approach is the subject of the compromise. Since ultimately this will depend on the needs of each implementing organization, it will be difficult if not impossible for the Technical Committee to provide a single recommendation if this approach is adopted.

An alternative approach that we are examining builds on the nested topic approach discussed previously in this document by introducing persistent object ids into the XSLT transform with the following process:

1. Aggregated document is created and saved as a map and topics. The ids of the topicrefs and topicheads are either set to the same values as their corresponding topics or to a predefined variant of the topic ids.

2. Map is edited as a standalone entity and extended with a number of elements and attributes

3. Map and topics are aggregated once again for authoring. Content of the map is not transformed into the aggregated document since there is no requirement for this content in the aggregated authoring use case.

4. The save process incorporates a transform that saves the modified topics and uses the mapped ids to:

a. Insert new topicrefs/topicheads into the map

b. Delete any topicrefs/topicheads and associated content that correspond to topics that were deleted from the map during the authoring session.

c. Change the location of topicrefs/topicheads and associated content within the map that correspond to topics that were moved in the aggregated document.

Corruption of Map Content or Context

The adoption of this approach would allow massive amounts of map content to not be reflected in the aggregated document. The following table identifies this in detail:

Table 2: Reconciliation of Map with Topics Nested in Ditabase

Elements in Map (base) Relationship to Topics Nested in Ditabase

(title) (optional)) Not replicated in the aggregated document

then (topicmeta) (optional) Not replicated in the aggregated document





then any number of anchor Not replicated in the aggregated document

or data Not replicated in the aggregated document

or data-about Not replicated in the aggregated document

or navref Not replicated in the aggregated document

or reltable Not replicated in the aggregated document

or topicref Logically derived from topic (or its specializations) when the topic appears with a body in the aggregated document. Reference persisted with id attribute.

or anchorref Not replicated in the aggregated document

or keydef Not replicated in the aggregated document

or mapref Temporarily not supported.

Logically derived from topic (or its specializations). Reference persisted with id attribute.

A mechanism for this has not yet been identified. Support for the feature is constrained by the need for non-ambiguous transformation of topics into a map structure. It is not expected that aggregated authors will be aware of map hierarchies, so logic will need to be based on structural patterns as opposed to attributes provided by the aggregated author.

or topicgroup Not replicated in the aggregated document

There is some question as to the effect of new topics and topicref moves on topicgroup and whether the aggregated authoring solution transforms will be able to incorporate sufficient logic. Use cases need to be identified.

or topichead Logically derived from topic (or its specializations) without a body. Reference persisted with id attribute.

or topicset Not replicated in the aggregated document

There is some question as to the effect of new topics and topicref moves on topicset and whether















the aggregated authoring solution transforms will be able to incorporate sufficient logic. Use cases need to be identified.

or topicsetref Not replicated in the aggregated document

There is some question as to the effect of new topics, and topicref moves on topicsetref and whether the aggregated authoring solution transforms will be able to incorporate sufficient logic. Use cases need to be identified.

The omission of so much map content has been a concern to the BusDocs subcommittee, and we have considered and debated how various edits of the aggregated document will affect the standalone map. While we have a potential action item to create use cases that would examine how the different content types would be affected, for now we would submit that this affects broad classes of content in the map:

Attributes that are added to the topicrefs and topicheads. The proposed approach uses the object ids to preserve these attributes, however the context of a topic can change in the aggregated authoring which could render the attributes as contextually incorrect. This of course is something that must be watched by map owners in any DITA implementation, whether it involved aggregated authoring or not.

Elements that can be contained within topicref or topichead as children.8 Since the suggested approach implements a one-to-one relationship between topicref and topichead in the map and a topic in the aggregated document, the ids should enable the persistence of these nested elements. Once again, changes to the topics themselves may invalidate the context of the elements.

Elements that can exist between topicref and topichead as peers. This is the most problematic class, since it can contain many use cases where there is ambiguity regarding how the peer element relates to the nearest topicref or topichead above and below it. Adding, deleting, or moving topics in the aggregated document can create orphaned elements with no way to automatically determine the proper action during the XSLT transform will rectify the issue. This final class of content does represent a class that is mostly specific to the aggregated authoring process. In a normal DITA map, topicrefs and topicheads are added, deleted, or moved by the map expert who has visibility of adjacent peer elements. The one case where a topic author can create orphaned content in the map is when topics are completely deleted without referential integrity being enforced.

This discussion illustrates that the need for map owners to reconcile the map with edits that occur in topics after the map is created is a general DITA process requirement, and not specific to aggregated authoring. Also, the need for the map owner in the aggregated authoring process to reconcile the map exists whether the map intelligence was added to a separate map or to the aggregation map. The key is that the additional intelligence added to the map is done so in accordance with the context of the aggregated document; if the aggregated document changes, map changes can be expected as well.

8 (topicmeta) (optional) then (anchor or data or data-about or navref or or anchorref or keydef or mapref or topicgroup or topichead or topicset or topicsetref).


http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicsetref.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicset.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topichead.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicgroup.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/mapref.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/keydef.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/anchorref.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/navref.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/data-about.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/data.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/anchor.html

http://docs.oasis-open.org/dita/v1.2/os/spec/langref/topicmeta.html



For this reason, it may not be necessary to eliminate standalone editing of the map; but it will be important to identify the types of impact a map owner can expect so that implementing organizations can make proper decisions.

Conclusion

The BusDocs subcommittee looks forward to discussions with the Technical Committee about the contents of this communiqué, and hopefully the creation of recommendations for aggregated authoring of topics and a map that can be available to interested organizations as soon as possible.


OASIS DITA BusDocs Subcommittee€¦ · Web viewBackground Members of the DITA for Enterprise...

Documents

Transcript of OASIS DITA BusDocs Subcommittee€¦ · Web viewBackground Members of the DITA for Enterprise...