SAIF DITA Project Strategy12/27/10 (by Karen Smith)

SAIF DITA PROJECT STRATEGY

ContentsDITA Project Goals.......................................................................................................................................3Why Use DITA?............................................................................................................................................3SAIF Book Requirements.............................................................................................................................3

SAIF DITA Project Tools............................................................................................................................4Tool Recommendations.......................................................................................................................6PDF Rendering Software......................................................................................................................6

SAIF DITA Outline........................................................................................................................................6SAIF Book Structure.................................................................................................................................7SAIF Topics - Organization.......................................................................................................................7SAIF Topics - Reuse..................................................................................................................................8SAIF Topic Owners...................................................................................................................................8DITA Topic Types.....................................................................................................................................8Topic Links...............................................................................................................................................8

Style Guide..................................................................................................................................................9Graphics.......................................................................................................................................................9

Visio and Enterprise Architecture Graphics...........................................................................................10PowerPoint Graphics.............................................................................................................................10SVG Graphics.........................................................................................................................................10

Concept Maps............................................................................................................................................10XTM Topic Maps....................................................................................................................................11

Audience of the SAIF Book........................................................................................................................11Executives..............................................................................................................................................11Architects...............................................................................................................................................11HL7 Work Groups..................................................................................................................................11Implementers........................................................................................................................................11

SAIF Release Levels....................................................................................................................................11Review Strategy.........................................................................................................................................12

Informal Reviews...................................................................................................................................12Formal Peer Reviews.............................................................................................................................12

Post-Peer Review Work.....................................................................................................................13Peer Review Plans..............................................................................................................................13

Output Formats.........................................................................................................................................13Where to Publish the SAIF Document.......................................................................................................14Training and Knowledge Transfer Material...............................................................................................14SAIF Content Management.......................................................................................................................14

Filename Conventions...........................................................................................................................14

1

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Filename Conventions for SAIF DITA Topics......................................................................................14SAIF Directory Structure....................................................................................................................15UUIDs for DITA Filenames..................................................................................................................15

Long-Term Content Management Goals...............................................................................................15Evaluation of Alfresco with Componize and XDocs by Bluestream....................................................16

Content Management Spreadsheets.....................................................................................................17Metadata Conventions..........................................................................................................................17

Joint SAIF/NCI Writing Project...................................................................................................................17ECCF Training Materials.....................................................................................................................17ECCF Implementation Guide..............................................................................................................17

Additional Questions.................................................................................................................................18SAIF DITA Design Summary.......................................................................................................................18

2

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

DITA Project GoalsThe goals of this project are to compile a SAIF “book” using DITA, convert the SAIF documents from Word format to DITA format, to set up a common, shared infrastructure for future maintenance of the SAIF material, and to develop training materials and processes for HL7 Publishing.

Why Use DITA?DITA is a structured information standard that OASIS manages. DITA stands for Darwin Information Typing Architecture and supports documentation that you can publish to various outputs, including HTML and PDF.

DITA is an XML-based, open standard that defines a consistent structure for content. It promotes information typing at the topic level, thereby enabling authors to consistently write, share, modularize, and reuse content.

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

With DITA, you can create a concept, task, reference, generic topic, or glossterm topic type. The current SAIF documents consist of 70% conceptual material, 30% reference material (tables, graphics, and glossaries), and 0% task (procedural) material. The Implementation Guide might include some 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 requires structured authoring, you can create a more consistent look and feel to the material, and enhance the usability of the content.

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

SAIF Book RequirementsThe ArB members expressed the following expectations for the SAIF book:

The SAIF book should be easy to maintain, with all changes traceable to previous versions.

Graphics, definitions, and explanations should be reusable, so that changes are made in one place, but automatically reflected where they are used.

3

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Each topic in the SAIF book should be identified individually to assist with indexing and version tracking. The outlines list each topic in the SAIF book.

The SAIF book should be fully 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.

Future versions of the SAIF book will use revision bars to indicate changes made since the publication of the last version. Angle brackets << and >> or a different color font will set off the revised text. (At this time, revision bars work in the XHTML and Word output formats but not in the PDF output.)

Reorganizing topics in the SAIF book should be easy to do, both as a permanent restructuring and as alternate views, without changing the primary structure.

The SAIF book should be able to be selectively packaged for different audiences.

A visual map of the SAIF book’s organization would be an advantage.

The SAIF book should be viewable via the web, but also as a printed document.

The SAIF book should be able to be produced in multiple formats.

More than one author should be able to maintain the SAIF book, with accountability for each section or topic.

The SAIF book content should be cohesive and logically consistent. The ability to use ontology tooling to evaluate would be an advantage.

Because the SAIF book is HL7’s initial exploration of DITA, this book should able to reference external content and display technical artifacts as well as graphics, tabular views, and clickable models.

The published SAIF book needs a “home” on the HL7 web site.

Metadata will be used to track versioning, author name, revision dates, search keywords, and other attributes.

SAIF DITA Project ToolsThe SAIF 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 A robust DITA editor such as oXygen for DITA authoring

4

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Inkscape (free SVG drawing program) Inkviewer (free SVG viewer program) DITA Open Toolkit for publishing DITA content A place for publishing the SAIF DITA book and related documents Information Architecture Workbench (free from IBM) XML Mind XSL Utility (free for outputting DITA to Word) Xenu for quickly checking links in the DITA output (free) A search program such as Agent Ransack or Wingrep for finding strings in the DITA source.

OXygen already has search functionality built in.

For phase 1, we used out-of-the-box DITA software and the default style sheet. For information on getting started with DITA as cheaply as possible, see http://dita.xml.org/wiki/getting-started-as-cheaply-as-possible.

During phase 1, Karen Smith used the Information Architecture Workbench to create ditamaps and to generate stub (empty) DITA topics. However, she stopped using IAW in phase 2 because it has not kept up-to-date with the DITA 1.2 functionality and because it is just as easy to create ditamaps and DITA topics using oXygen. To download and install the Information Architecture Workbench, see: https://www14.software.ibm.com/webapp/iwm/web/preLogin.do?lang=en_US&source=swg-iiaw

For phase 2, we are using oXygen XML Author for the SAIF DITA project.

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

OXygen: Excellent low-cost and cross-platform DITA authoring tool; recommended by Scriptorium Publishing ($434.80 for Enterprise edition, plus $100/yr for maintenance). OXygen comes in two flavors for businesses: Professional and Enterprise. Both the Professional and Enterprise editions offer the same DITA functions, but you can integrate the Enterprise edition with a database or content management system. See http://www.oxygenxml.com/

XMetal Author by JustSystems: Very powerful DITA authoring tool with enhanced PDF support ($874 per user for license and maintenance). Many technical writing organizations use XMetal. XMetal also is integrated with several Component Content Management (CCM) products. However, XMetal works on Windows only. See http://na.justsystems.com/content-xmetal-author

Enterprise version of Serna XML Editor: Full-featured XML editor, similar to oXygen ($749 plus $199 for maintenance for 1 year). Serna also provides the Serna XML Free editor with a limited set of DITA functions. See http://www.syntext.com/shop/pricing/serna-enterprise/

Arbortext Publishing Engine: Very powerful DITA authoring tool, designed to work with fully implemented content management systems. See http://www.ptc.com/products/arbortext/publishing-engine/

Structured FrameMaker: Designed for publishing books. Has a superior PDF publishing engine and DITA plug-ins, but not practical to use unless your documents are already in FrameMaker ($999)

5

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

MadCap Flare: Powerful tool for single-sourcing content in multiple formats. The current version (5.0) can import and publish DITA content, but it does not support native DITA authoring. ($899)

DITA Storm Editor: See http://www.inmediusdita.com/ XMLMind Enterprise XML Editor: This DITA editor comes packaged with Bluestream XDocs CCM

product. XMLMind also offers a free personal editor with limited DITA functions and a converter program that converts documents from one format to another. See http://www.xmlmind.com/xmleditor/

Altova XML Spy: This XML editor is designed to help developers create schema on which authoring solutions depend. XML Spy includes DITA templates only.

Tool RecommendationsAfter evaluating trial versions of oXygen Enterprise 11.2 and XMetal Author 6.0, HL7 decided to purchase three oXygen licenses for phase 2. OXygen is a low-cost enterprise-level DITA authoring tool with additional XML functions and support for database integration. For a detailed comparison of these tools and product information, see http://wiki.hl7.org/index.php?title=XML_Tool_Considerations on the SAIF Editing Crew wiki. We also consulted with ITHSDO and considered their findings. They also are using the oXygen editor.

PDF Rendering SoftwareCreating PDF output requires special software for rendering PDFs. DITA Open Toolkit and oXygen come packaged with the IDIOM FO PDF renderer, which works well for creating basic PDF output.

XMetal is packaged with the RenderX XEP program (http://www.renderx.com/), which has additional functionality and works more quickly. PDFs created with XEP have nicer formatting and table layout, and support indexes. Because HL7 is a standards development organization, we were able to obtain free XEP licenses. Normally XEP costs around $350 per license.

The high-end PDF renderer is the Antenna House PDF formatter (http://www.antennahouse.com/), which costs quite a bit more. You can use either XEP or Antenna House with oXygen.

SAIF DITA OutlineKaren Smith created an outline of the master SAIF document, which followed the structure that the ArB proposed for the SAIF book. For ease of readability during reviews, she created separate outlines for each major section.

The SAIF document consists of a master ditamap file (table of contents with pointers to individual files) with several sub-ditamap files for each major section, and many DITA “topic” files.

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

6

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

SAIF Book StructureThe following is the proposed SAIF book structure. The SAIF book is being developed in stages.

1. Executive Overview2. SAIF Overview 3. SAIF Introduction4. Enterprise Conformance and Compliance Framework (ECCF) 5. Governance Framework6. Behavioral Framework7. Information Framework8. SAIF Implementation Guide (includes HDF, Facilitator’s Guide and Handbook)9. Practical and Operational Perspectives of SAIF tutorial10. Glossary

During phase 1, the SAIF book consisted of the following sections: SAIF overview SAIF introduction ECCF Glossary

During phase 2, the SAIF book consisted of the following sections: SAIF executive overview SAIF overview SAIF introduction ECCF Governance Framework stub topic and ditamap Behavioral Framework Information Framework stub topic and ditamap Implementation Guide stub topic and ditamap Practical SAIF tutorial (stub topic) Glossary

The Governance Framework, Information Framework, Implementation Guide, and the tutorial will be included in the SAIF book during phase 3 (in 2011 and beyond).

SAIF Topics - OrganizationThe SAIF DITA book includes the information from the Word documents and additional information from the PowerPoint slides. The topics have similar level of granularity as the PowerPoint slides, although the topics are often longer than individual slides.

Each topic covers some or all of following content:

7

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Key idea (in the “short description” section of each topic) Explanation of the key idea Transitions or links to related topics Subtopics that explore this key idea in greater detail

SAIF Topics - ReuseCurrently, the SAIF book reuses little content – mostly graphics and definitions. However, we probably will reuse more content when we start producing different versions of the SAIF Implementation Guide for various audiences.

SAIF Topic OwnersEach major section will have a primary topic owner and a backup topic owner:

Executive overview – Steve Hufnagel (primary), Ron Parker (backup) Introduction – Ron Parker (primary), Andy Bond (backup) ECCF – Charlie Mead (primary), Steve Hufnagel (backup) Governance Framework– Jane Curry (primary) Behavioral Framework – John Koisch (primary), Wendell Ocasio, Cecil Lynch (backups) Information Framework – Cecil Lynch (primary), Ann Wrightson (backup) Implementation Guide – various authors (phase 3) Practical SAIF – TBD (phase 3) Glossary – Publishing and Wendell Ocasio

DITA Topic TypesDITA provides templates (also called “topic specializations”) for different types of topics. The SAIF document uses the following DITA topic templates:

Concept Reference Topic Glossentry Composite

For more details, see “Topic Templates” in the DITA Processing paper.

Topic LinksOne cool thing about using DITA is how easy it is to create links between topics and other DITA documents and external web sites. XHTML output contains the greatest number of links while PDF output contains much fewer links. You can have many different types of links in a DITA document:

Table of contents. The TOC is created automatically and displays in both PDF and XHTML output)

Child, parent, and family links. These links are created automatically during the build, and display in XHTML output. Each child link provides a short description of the topic.

8

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Inline links. These cross-references to specific DITA topics are created manually and display in both PDF and XHTML output.

Relationship links. These links display in XHTML and Word output. You can create a related link in two ways:

o In a relationship table in the ditamap fileo In the related-links section of a DITA topic

In XHTML format, each DITA topic automatically links to its parent topic and children topics in the topic hierarchy. You also can access topics from the table of contents. Some of the topics have links to other topics and still other topics are “transitional topics” that transition from one subject to another.

In PDF format, the DITA document has a table of contents and inline links to specific topics, similar to what you would find in a Word document. It also displays inline cross-reference links but not the links from the relationship table or related-links section.

In Word format, the DITA document displays the table of contents, inline links, and related links, but not the “family” links.

Style GuideKaren Smith developed a DITA style guide to help ensure consistency throughout the SAIF DITA document. The DITA style guide is included in the DITA Processing paper.

GraphicsThe SAIF DITA document uses bitmap (PNG) format for graphics. The graphics are referenced in the DITA topics as images. DITA projects follow the web practice of referencing images that are stored in a specific directory. You can reuse a particular graphic can in a DITA document.

The best graphics format to use in a DITA document depends on the type of graphic and the output format for the document. PNG format is best for vector and PowerPoint drawings. GIF is best for simple, small graphics such as logos and icons. JPG is the best format for photographs. The graphics use 24-bit color format.

The bitmap graphics are sized differently for PDF and XHTML output. For XHTML output, the graphics should be 96 dpi. For PDF and Word output, the graphics should be at least 150 dpi and no bigger than page width (about 7 inches wide).

Both the SVG and PNG versions of the graphics are stored in SVN. These SVG graphics are higher resolution than the PowerPoint graphics and the font displays much better in the DITA output.

Visio and Enterprise Architecture GraphicsRecommendation: DITA does not support rendering of Visio (VSD) graphics. To use Visio graphics in a DITA document, they need to be saved as SVG or EMF and then to PNG format.

9

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

The ArB authors should save Visio and Enterprise Architecture graphics in either SVG or EMF format. If the graphics are already in SVG format, then Technical Publishing could export them to PNG format. If the graphics are in EMF format, then Technical Publishing could convert them to SVG format and export them to PNG format for the DITA document.

PowerPoint GraphicsIf one saves PowerPoint graphics as PNG files, they display quite poorly in the DITA output. To ensure that the PowerPoint graphics display well in the DITA output, one needs to export them to EMF format, convert them to SVG format and then to PNG format.

SVG GraphicsSome DITA authors use SVG graphics directly in their DITA document. However, using PNG graphics instead was the better strategy. Only the Firefox browser and PDF are able to display native SVG graphics from DITA output. Internet Explorer does not support SVG graphics unless you download a special plug-in.

Concept MapsTo help organize and understand the voluminous SAIF material, we have been using the Cmap tool to create three different types of concept maps:

System maps Navigational maps Relationship maps

You can create a system map to illustrate to a customer how SAIF or a component of SAIF works and show the relationships between different concepts, or create a navigational map to help organize the material for a section of the SAIF DITA book. A relationship map is a special type of navigational map that shows the non-hierarchical relationships between SAIF concepts in the DITA book.

All of the Cmaps in the SAIF document except one are system maps.

The SAIF concept maps are stored on the Cmaps server. Periodically, the Cmap files are zipped and backed up to SVN in the SAIF_maps directory. The instructions for using the CmapTools and the SAIF Cmap Sandbox are stored in SVN in the cmap_sandbox directory.

XTM Topic MapsCecil 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 topic maps. Topic maps are similar to ditamaps, except ditamaps apply to technical documentation, while topic maps are for organizing and managing knowledge. No XTM deliverables are expected for the SAIF project.

10

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Audience of the SAIF BookThe major audiences of the SAIF book include executives who are interested in implementing working interoperability for their organization, architects who want to evaluate whether to use SAIF to implement Working Interoperability, business analysts, HL7 work groups, and implementers. (The different types of architects include the following: enterprise, business, information, solution, and technical.) The target audiences for the NCI ECCF Implementation Guide are adopters, adapters, and developers (implementers).

The major SAIF topics for each target audience are listed below. For phases 1 and 2, we will have one “view” of the SAIF book. However, you can publish just the executive overview topic independently from the rest of the SAIF document. In phase 3, we hope to have a couple of views of the SAIF book for different audiences – one view for architects and another view for implementers.

ExecutivesThe executives would read the executive overview and the SAIF overview.

ArchitectsArchitects might skim through the SAIF book or read it from cover to cover, depending on their focus. For example, architects who want to adopt or adapt Working Interoperability for their organization only need to understand general SAIF concepts while an architect who wants to build a complete Working Interoperability solution needs to understand SAIF at a deep level.

HL7 Work GroupsHL7 work group members who are interested in participating in the SAIF project also would benefit from reading the SAIF book, especially the sections that pertain to HL7 activities and history.

ImplementersThe Implementers would read the Implementation Guide and the major sections of the SAIF book, except the appendixes, which provide historical and supplementary information.

SAIF Release LevelsThe SAIF book is updated periodically, as new material is written and existing material is revised.

For the first release, the SAIF DITA book included the Executive Summary, Introduction, Glossary, and ECCF material from the SAIF Decks 1-5.

For the second release, SAIF DITA book included updates to the existing material.

For the third release, SAIF DITA book will include the rest of the new material and the enhanced glossary. The SAIF book might include two views – one view for executives and another view for implementers.

Release level numbers:

11

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

January 2010 publication (Version 1.00) May 2010 publication (Version 1.10) July 2010 review (n/a – no new material ) January 2011 publication (Version 2.00)

Review StrategyThe SAIF document undergoes both informal and formal peer reviews during the release cycle. Informal reviews occur whenever is convenient for the technical editor and authors. The ArB co-chairs coordinate the formal peer review. The peer review took place in spring 2010. For 2011, the ArB will target specific individuals and groups to review the SAIF material rather than doing a second peer review.

Informal ReviewsDuring the editing phase, the technical editor submits the Word drafts to the original authors and interested parties for an informal review. They make their changes and return the drafts to the technical editor for additional editing work. This back-and-forth process occurs until the draft is ready for publication. Finally, the technical editor converts the material to DITA and adds it to the SAIF DITA document.

Formal Peer ReviewsIn April and May 2010, the ArB (co-chairs Ron Parker and Tony Julian) held a formal peer review of the SAIF Introduction, ECCF, and Behavioral Framework chapters.

The ArB follows a specific format for peer reviews. The documents must be in PDF format with line numbers. The peer reviewers use a special spreadsheet to record their comments by line number. To prepare for the peer review, the technical editor creates line-numbered Word output from the DITA source files, saves the files as PDFs, and posts them to the peer review directory on GForge.

After the peer review ends, the authors and volunteers classify the review comments according to specific criteria (see Table 1) and add suggested corrections to their copy of the spreadsheet.

The peer review co-chairs consolidate all the comment dispositions onto one spreadsheet and make it available to the authors.

Category Comment Type

1 This comment is a typo or grammatical error.

2 Content is wrong.

3 Content needs harmonization with ECCF.

4 Content needs harmonization with BF.

5 Content needs harmonization with INTRO.

12

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

6 Content needs harmonization with GF.

7 Content needs harmonization with IF.

8 Good point – the content needs to be expanded.

Table 1: Review comment classification.

Post-Peer Review WorkAfter all comments are classified, the technical editor updates the LATEST Word documents with the minor comments, which are available on the GForge peer review site. Then the editor turns the documents over to the technical authors to incorporate the comments that require technical and HL7 expertise. When the authors are done with their updates, they send the document to the technical editor for an edit. Then the technical editor folds the revised content back into the DITA document.

Peer Review PlansThe ArB has asked individuals and organizations to review the new SAIF material rather than undergoing a second peer review in 2011.

Important: Our long-term goal is to have the authors update the DITA source files with the review comments instead of going back to the Word source. This will require training people to use DITA.

Output FormatsThe output formats for published SAIF releases are XHTML and PDF. It is possible to publish subsections of the SAIF book or a single topic; for example, publish just the Behavioral Framework material.

The output format for peer reviews is Word. The peer review documents are line numbered and saved as PDFs.

Where to Publish the SAIF DocumentThe SAIF output files are stored on GForge for readers to download. After the Governance Framework and Information Framework sections are completed, Publishing will work with Ron Parker to publish the SAIF document in XHTML and PDF format on the HL7 web site.

13

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Training and Knowledge Transfer MaterialKaren Smith has developed a set of training materials to help teach the Publishing department and the ArB authors about using DITA for the SAIF project. The DITA Processing paper describes the processes for working on the SAIF DITA book and includes a DITA style guide. The DITA Required Reading List handout serves as a self-study course to learn DITA.

You can access these documents through SVN or on GForge.Document Title SVN LocationDITA Processing paper and style guide

http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/dita_training_materials/DITA_PROCESSING_PAPER.docx

DITA Required Reading List (self-study)

http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/dita_training_materials/DITA_Required_Reading_List.docx

DITA training materials http://gforge.hl7.org/gf/project/saeaf/docman/?subdir=305

SAIF Content ManagementThe SAIF source topic files and the output files (in zipped format) are stored in SVN in the SAIF-dita directory. For the path, see:

http://gforge.hl7.org/gf/project/saeaf/docman/?subdir=125 (GForge)http://gforge.hl7.org/svn/saeaf/trunk/docs/saeaf-dita (SVN)

Filename ConventionsThe DITA files use the following file naming convention: <component_name>_<unique_filename>.dita

The graphics use the following filename convention: <component_name>_<unique_filename>.png

Filename Conventions for SAIF DITA TopicsEach major component has a unique prefix. Each topic file consists of the component prefix and a unique filename based on the topic title. For example, "SAIF Overview" is in the SAIF_overview.dita file and its topic ID is “SAIF_overview.” Each DITA topic has an ID based on its filename.

For the filename conventions for the DITA files and graphics, see “SAIF Filename Conventions” in the DITA Processing paper.

SAIF Directory StructureThe working graphics for the authors to use are stored in the saif-dita-source-files\graphics directory. However, the source SVG and bitmap graphis are stored in the saif-graphics directory in SVN.

The SAIF DITA source and output files are stored in the following SVN directories under saeaf-dita:

saeaf_dita

14

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

saif_archived_buildssaif_output_builds

saif_html_buildssaif_pdf_buildssaif_word_builds

saif-dita-source-files<various top-level .dita files, SAIF.ditamap, SAIF.ditaval>

bfcustomized_fileseccfgf glossarygraphicsiguideinfofintro saifex (doesn’t exist yet)

saif-graphicsfinished_graphics

new_graphicsresized_for_builds

html_graphicspdf_graphics

vector

UUIDs for DITA FilenamesIn the future, HL7 might want to consider using universally unique identifier (UUIDs) for DITA filenames or topic IDs to ensure that they are unique across various HL7 and SDO documentation sets. Using UUIDs also would require a tool to generate a human-readable view of the topic titles, links, and content references.

Note: oXygen supports generating UUIDs for element IDs.

Long-Term Content Management GoalsEventually, (especially if HL7 adopts DITA for the hundreds of documents that it produces), HL7 will benefit from a component content management system (CCM) to keep track of hundreds of DITA files and graphic files, collect metadata, and reuse them for different projects. We also need to keep track of versioning of files when the content changes, when files and ditamaps are reused across projects, and changes to ownership of files. A CCM also keeps track of the links between topics.

Some CCMs are general purpose while others are specialized for DITA projects. The specialized CCM products are tightly integrated with certain DITA editors (especially XMetal). You can use a DITA-aware CCM product to do the following tasks:

15

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

Store DITA and associated files in a repository. Control versioning of files (similar to SVN). Manage DITA and associated files across releases. Manage relationships, content references, and links between topics over time. Automate workflow processes. Publish DITA output. Track metadata. Handle translation into multiple languages.

A good general-purpose CCM can store documents in various formats. You could store XML documents as a complete file or chunk them into modules that are easy to update, manage, and reuse. You could also store Word and PowerPoint documents in the CCM and attach appropriate metadata to help you manage each object. You could store the DITA and graphics files in the same CCM using its associated DITA support tools (support for the ditamap and maybe DITA Toolkit). Having one system is helpful when you want to manage a variety of related data types (Word, PowerPoint and DITA documents all related to the same product or component).

Evaluation of Alfresco with Componize and XDocs by BluestreamWe evaluated two different CCM products. Alfresco with the Componize add-on would be a good choice if HL7 wants a CCM that manages all types of documents including DITA documents. Componize supports DITA. Alfresco is free and Componize is available on a subscription or on-demand basis. Implementing Alfresco requires more technical expertise than implementing XDocs, which is designed with the non-technical user in mind.

Bluestream XDocs is a DITA-specific CCM that costs about $5000 for a server license plus additional maintenance fees. XDocs also provides add-ons for managing workflow and a knowledge base.

Other DITA-aware CCMs on the market include: x:Point for Microsoft SharePoint (requires a SharePoint server) SDL Trisoft Astoria Vasont DocZone Dita Exchange (also requires SharePoint)

Content Management SpreadsheetsAvailable are several spreadsheets for tracking the SAIF DITA content:

SAIF build tracking for tracking the build and release versions. (See http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/Editing_project_docs/saif_versioning.xlsx.)

16

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

SAIF workflow snapshot to show where we are in creating the final SAIF DITA document. (See http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/Editing_project_docs/saif_workflow.xlsx.)

DITA topic spreadsheet for managing the DITA content over time. (See http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/cms_spreadsheets/_dita_metadata_2010-07-06.xlsx.)

Spreadsheet for showing which DITA topics contain which graphics. (See http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/cms_spreadsheets/_Figs_in_DITAFiles.xlsx.)

Spreadsheet for tracking the graphics work (See http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/cms_spreadsheets/_Allgraphicsfiles_in_DITAfiles.xlsx.)

Metadata conventions. (See http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/Editing_project_docs/saif_metadata.xlsx.)

Metadata ConventionsMetadata is useful for keeping track of such things as the author’s name, publisher, copyright date, and search keywords. Search keywords are useful for searching on the web. One of the reasons for using DITA is the ability to add built-in metadata and make information easy to find.

The saif_metadata.xlsx spreadsheet shows the metadata conventions for the SAIF DITA book.

Joint SAIF/NCI Writing ProjectJane Curry is coordinating the joint SAIF/NCI writing project. We are working with NCI on a common design strategy for the documents.

ECCF Training MaterialsA writer from the National Cancer Institute (NCI) developed an instructional framework for teaching users how to document the needed artifacts for filling out the ECCF template.

ECCF Implementation GuideThe NCI technical editor is using DITA to document artifacts for services using the ECCF specification stack template. Another team at NCI is writing the NCI ECCF Implementation Guide.

Additional Questions1. Where will we publish the SAIF DITA book? Publish to the HL7 web site.2. Which output formats do we want? Publish to XHTML, PDF, and Word.3. Will we be using collaborative authoring? Yes. DITA is great for collaborative authoring.

17

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

4. Do we want a customized style sheet or use the default style sheet? We will use the default style sheet and consider customizing it for future releases.

5. Do we want to include metadata in the DITA topics? Yes! 6. Do we want to use UUIDs for DITA filenames? Save this idea for the future. OXygen supports

the use of UUIDs for element IDs.

SAIF DITA Design SummaryThis section summarizes the major design considerations and tools for the SAIF DITA project.

Design Item Description

DITA editor oXygen Enterprise

Output formats XHTML, TOCJS, Webhelp, PDF, Word

PDF rendering RenderX XEP

Document organization Organized like a book starting with the introduction, SAIF frameworks, the implementation material, and a comprehensive glossary.

Ditamap structure Master ditamap with sub-ditamaps for each major section

Topic structure Each file contains one topic.

Topic types Concept, reference, glossentry, topic

DITA customization None

Style sheets Default CSS stylesheet for XHTML and XSLT stylesheet for PDF

Graphics programs Visio, PowerPoint, Enterprise Architect, SVG

Graphic formats PNG

Graphic resolution 96 dpi for XHTML, 150 dpi for PDF

Project management Spreadsheets

Component content management

Spreadsheets

Version control SVN

Hosting location Currently, the SAIF output files are stored on GForge at http://gforge.hl7.org/gf/project/saeaf/docman/?subdir=125. Our goal is to

18

SAIF DITA Project Strategy12/27/10 (by Karen Smith)

host the SAIF DITA document on the HL7 web site.

Translation into other languages

None at this time

Content reuse Yes, where applicable

19