SAEAF DITA Project Strategy

12/11/09 (by Karen Smith)

SAEAF DITA PROJECT STRATEGY

Contents

DITA Project Goals

Why Use DITA?

SAEAF Book Requirements

Current Tools Used in Phase 1

Our tool recommendations

SAEAF DITA Outline

SAEAF Topics - Organization

SAEAF Topics - Reuse

SAEAF Topic Owners

DITA Topic Types

Topic Links

Graphics

Audience of the SAEAF Book

Executives

Architects

HL7 Work Groups

SAEAF Release Levels

Concept Maps

XTM Topic Maps

Output Formats

Content Management

Where to Publish the SAEAF Document

Joint SAEAF/NCI Writing Project

Additional Questions

1

SAEAF DITA Project Strategy

12/11/09 (by Karen Smith)

DITA Project Goals

The goals of this project are to compile a SAEAF “book” using DITA, convert the SAEAF documents from Word format to DITA format, and to set up an a common, shared infrastructure for future maintenance of the SAEAF material.

Why Use DITA?

DITA is a structured information standard, whichthat is managed by OASIS. DITA stands for Darwin Information Typing Architecture and supports documentation that can be web based as well as traditional document basedpublished to various outputs, including HTML and PDF.

DITA is implemented in XML. DITA is an XML-based, open-content standard that defines a common consistent structure for content. thatIt promotes information typing at the topic level, thereby enabling authors to the consistent creation, sharing, and reusconsistently write, share, modularize, and reuse contente of content.

DITA is topic oriented. Each A DITA topic covers a single concept or idea, similarly to what a PowerPoint slide does. However, aA DITA topic can be longer and more detailed than a PowerPoint slide, thoughand it can contain other topics.

With DITA, you can create a concept, task, or reference topic type. The current SAEAF documents consist of 90% conceptual material, 10% reference material (tables, graphics, and glossaries), and 0% task (procedural) material. Further phases are expected to add more task-oriented guidance.

DITA allows you to reuse content and graphics in different documents. In DITA, you add topics to a DITA map file to create a document, much like a book with a table of contents. You can reuse a topic in multiple map files if you need to create multiple documents.

Because DITA supports requires structured authoring, you can create a more consistent look and feel to the material, and enhance the usability of the content. [EV1]

You can publish DITA material in several different outputs. formats, depending on the publishing tools that are available.The available outputs are somewhat dependent on tools, but most tools enable authors to create customized output targets.

SAEAF Book Requirements

The following expectations for the SAEAF Book that were expressed include:

  • The SAEAF book should be easy to maintain, with the impact of all changes traceable to previous versions.
  • Graphics, definitions, and other core explanations should be reusable, so that changes are made in one place, but automatically reflected where they are used.
  • More than one view of the material should be able to be produced to cater to different audiences.
  • Each topic in the SAEAF book should be individually identified to assist with indexing and version tracking. The outlines list each topic in the SAEAF book.
  • The SAEAF Book should be able to be searched when in digital form to find selected keywordsfully searchable using keywords.
  • Updates should be able to be applied selectively, without losing traceability. The ability to restore to a previous version selectively is also important.
  • Reorganizing topics in the SAEAF book should be easy to do, both as a permanent restructuring and as alternate views, without changing the primary structure.
  • The SAEAF Book should be able to be selectively packaged for different audiences.
  • A visual map of the SAEAF book’s organization would be an advantage.
  • The SAEAF Book should be viewable via the web, but also as one or more traditional documentsas a printed document.
  • The SAEAF Book should be able to be produced in more than one formatmultiple formats.
  • The SAEAF Book should be able to be maintained by more than one author, with accountability for each section or topic.
  • The SAEAF Book content should be cohesive and logically consistent. The ability to use ontology tooling to evaluate would be an advantage.
  • Because the SAEAF book is HL7’s initial exploration of DITA, consideration should be given to being able to reference external content and display technical artifacts as well as graphics, tabular views, and clickable models.
  • The published SAEAF Book needs a “home” on the HL7 web site.

This project will determine which of the requirements can be done with free tools and which require more capable but commercial tools, which may require custom configuration or programming.

Current Tools Used in Phase 1

The SAEAF DITA project requires the following tools:

  • Microsoft Office (Word, PowerPoint, Excel)
  • Concept map software and server (free Cmap tool)
  • SVN and GForge access for storing documents
  • Free Serna XML editor for DITA authoring
  • DITA Open Toolkit for publishing DITA content
  • A place for publishing the SAEAF DITA book and related documents
  • Information Architecture Workbench (free from IBM)

For phase 1, we will be using out-of-the-box DITA software and the default style sheet. For information on getting started with DITA as cheaply as possible, see

I will use the Information Architecture Workbench to create ditamaps and to generate stub (empty) DITA topics. To download and install the Information Architecture Workbench, see:

For phase 2, we would require an enterprise-level DITA authoring tool that supports more functionality, advanced output formats, and allows multiple authorsmultiple authoring capability. If we want to customize the style sheet, incorporate advanced search capabilities, or set up an Eclipse Information Center for the published content, we would need help from a DITA tools programmer.

The following lists some good enterprise-level DITA authoring software to consider.

  • OxygenoXygen –:eExcellent low-cost DITA authoring tool; recommended by Scriptorium Publishing ($349 professional to $449 enterprise, plus $100/yr for maintenance)
  • Enterprise version of Serna XML Editor:Full-featured XML editor, similar to oXygen ($749 plus $199 for maintenance for 1 year)
  • XMetal Author by JustSystems: – vVery powerful DITA authoring tool with enhanced, great PDF support ($1457)
  • Arbortext Publishing Engine:– vVery powerful DITA authoring tool, designed to work with fully implemented content management systems (really expensive; need to contact sales for prices).
  • Structured FrameMaker --:gDesignedood for large book-like documentspublishing books, easy to convert to DITA, generates great PDFs, . Has a superior PDF publishing engine and DITA plug-ins, but not practical to use unless your documents are already in FrameMaker ($999)
  • MadCap Flare version 9 --:useful for tutorialsPowerful tool for single-sourcing content in multiple formats. The current version (5.0) can import and publish DITA content, but it doesn’t support native DITA authoring., ability to convert to DITA, doesn’t support DITA specializations, can’t use for authoring new DITA content, lets you format the layout with CSS styles ($899)

Our tool recommendations

For Phase 2, Wwe recommend Oxygen for a low-cost enterprise-level DITA authoring tool, or XMetal from JustSystems in Canada as a powerful, high-end DITA authoring tool in phase 2.

SAEAF DITA Outline

I am creating an outline of the master SAEAF document, which follows the structure that the ArB has proposed for the SAEAF book as much as possible. For ease of readability during reviews, I have separated the outline into major sections – Introduction, ECCF, Governance, and Behavioral Framework. Then I will incorporate each section into the master outline.

The SAEAF document will consist of a ditamap (table of contents) file and many XML “topic” files.

If you have a chunk of content that is always used as a set, keeping it in its own ditamap file also lets you reuse it as-is in other deliverables.

This is the proposed SAEAF book structure. The sections in red text will be included in the phase 2 release of the SAEAF DITA document because the source documents have not yet been written. However, I will include single “stub” topics for sections 6-8.

  1. Executive overview
  2. SAEAF Introduction
  3. Enterprise Conformance and Compliance F (ECCF), including refinement and localization
  4. Governance Framework
  5. Behavioral Framework
  6. Information Framework
  7. Implementation Guide (includes HDF, Facilitator’s Guide and Handbook)
  8. Examples and lessons learned
  9. Glossary

SAEAF Topics - Organization

The SAEAF DITA book will include the information from the Word documents and the additional information from the PowerPoint slides. The topics will have similar level of granularity as the PowerPoint slides, although the topics would often be longer than individual slides. (Note: Often, one to four PowerPoint slides represent a single topic or concept.)

I favor this method as being the most usable way to present the SAEAF content. The advantage of this method is that the PowerPoint slides already present specific topics. The disadvantage of this method is that it will take longer to create the topics because I will need to add in the details from the Word documents.

Each topic will cover some or all of following content:

  • Key idea
  • Explanation of the key idea
  • Transitions or links to related topics
  • Subtopics that explore this key idea in greater detail

SAEAF Topics - Reuse

I also will look for sections of the existing SAEAF documents (especially the graphics) that can be reused.

SAEAF Topic Owners

Each major section will have a primary topic owner and a backup topic owner. For now, the original authors are the topic owners:

  • Executive overview – Charlie Mead (primary), TBD (backup)
  • Introduction – Charlie Mead (primary), Alan Honey (backup)
  • ECCF – Charlie Mead (primary), John Koisch (backup)
  • Governance Framework– Jane Curry (primary)
  • Behavioral Framework – John Koisch (primary), Wendell Occassio, Alan Honey, Cecil Lynch, Paul Boyes (backups)
  • Information Framework – Andy Bond (phase 2)
  • Implementation Guide – TBD (phase 2)
  • Examples – TBD (phase 2)
  • New NCI material about artifacts – NCI technical writers (Joe Platt and Eddie VanArsdall)
  • Glossary – TBD (anyone could volunteer)

DITA Topic Types

DITA provides templates (also called “topic specializations”) for different types of topics. Note: The new Learning and Tutorial templates will be available in DITA 1.2 several months from nowduring the first quarter of 2010, but they are already available in some authoring tools.

Topic type / Use in SAEAF document / Description
Concept / This template will be used for the conceptual and historical SAEAF material. / Use this workhorse topic template to explain a concept. This template offers a flexible structure.
Task / SAEAF doesn’t have any procedures yet, so this template won’t be used in phase 1. / Use this topic template to describe a procedure or a set of instructions. This template is tightly structured and offers a more limited set of DITA tags.
Reference / This template will be used for the large lookup tables, topics that are graphics only, and SAEAF examples. / Use this topic template for factual information such asthat is supported by lookup tables, graphics, lengthy examples, or other reference information.
Topic / We will explore how to use this template – perhaps transitional topics to assist with cross-mapping. / This was the original DITA topic template. You can use this topic for anything that doesn’t fit into the other categories (concept, task, or reference).
Composite / Some of the SAEAF information includes a mixture of conceptual and reference information, so we could use this template for those topics. / Use this template for complex topics that include conceptual, reference, glossary, or task information.
Glossary / I will try using the glossary topic template inside of a reference topic template. / Use this new template for glossary definitions. The glossary definitions worked better when I put them inside a reference topic template.
FAQ / Doesn’t apply to SAEAF material at this time; -- may be used for phase 2. / Use this new template for questions and answers (FAQs).

Topic Links

If we publish the SAEAF book in one of the HTML formats, each DITA topic automatically gets a linklinks to its parent topic and children topics in the topic hierarchy. You also will be able to access topics from the table of contents. Some of the topics will have cross-linkslinks to other topics and still other topics will be “transitional topics” that transition from one subject to another.

However, if we publish the SAEAF book in PDF format, it will have a table of contents and cross-references to specific topics, similar to what you would find in a Word document.

Graphics

I will need to convert the PowerPoint graphics to picture format for the SAEAF DITA project. The best graphics format to use depends on the type of graphic and the output format for the document. Because all the graphics are PowerPoint or Visio drawings, the best graphics format to use would be .PNG or .EMF[EV2]. The graphics will be in 24-bit color format.

The graphics will be embedded referenced in the DITA topics as images[EV3]. The key graphics, such as the Working Interoperability and specification stack graphics, will be in separate DITA topics. These graphical topics will include the text explanation that you see in the PowerPoint slides for those graphics. Other graphics will be included with the text in the DITA topics.

At some point, I would like to convert the PowerPoint graphics to a vector format, such as CorelDraw or Photoshop Adobe Illustrator, and store them in SVN. Then folks could grab these graphicsexport these graphics to a format that is usable in to use in PowerPoint presentations or save them in pictureexport them to a format to usethat is usable in the DITA topics.[EV4]

Audience of the SAEAF Book

The three major audiences of the SAEAF book include executives and managers who are interested in implementing working interoperability for their organization, architects who want to evaluate whether to use the SAEAF to implement working interoperability, and HL7 work groups. In phase 2, SAEAF implementers will be added to the audience mix. The NCI editors are focusing on the implementers for the types of projects which they are interested in.

Below I’ve listed the major SAEAF topics for each target audience. For phase 1, we will have one “view” of the SAEAF book due to lack of time. In phase 2, we would like to have multiple views of the SAEAF book for different audiences.

Executives

  • Non-technical executive overview
  • SAEAF Introduction
  • Overview
  • Simpler SAEAF complexity map
  • Working interoperability (just an overview)
  • SAEAF overall framework
  • Summary
  • ECCF introduction only
  • Governance
  • Introduction
  • Governance by organization type
  • BF introduction only

Architects

All of the SAEAF book except for the historical section of the Introduction. They will get the more technical executive overview that is in Deck 5 and the SAEAF complexity map that John Koisch created.

HL7 Work Groups

They are the lucky ones who will get the entire SAEAF book.

SAEAF Release Levels

The SAEAF book will be updated periodically, as new material is written and existing material is revised.

For the first release, the SAEAF DITA book will include the Executive Summary, Introduction, Behavioral Framework, Governance Framework, and ECCF material from the SAEAF Decks 1-5. The SAEAF book will include a single view – for architects and HL7 work groups.

For the second release, SAEAF DITA book will include the rest of the new material and updates to the existing material. The SAEAF book will include multiple views – for executives, architects and HL7 workgroups, and implementers.

Concept Maps

To help organize and understand the voluminous SAEAF material, we have been using the Cmap tool to create concept maps. You can use these maps to illustrate how SAEAF or a component of SAEAF works, [EV5]or to organize the material for the outline for each major section of the SAEAF DITA book. Go to the Cmaps server for the latest version of the concept maps. Periodically, the Cmap files are zipped and backed up to SVN in the saeaf_maps directory. The instructions for using the CmapTools and the SAEAF Cmap Sandbox are stored in SVN in the cmap_sandbox directory.

XTM Topic Maps

Cecil Lynch has volunteered to use OWL to convert the concept maps to XTM topic maps. Jane will be doing her own research on ISO Topic Maps to support strategic Tooling plans, so will also participate in the investigation of how to use the XTM topic maps. No XTM deliverables are expected for phase 1.