SAIF DITA PROJECT STRATEGY by FYNZ4s

VIEWS: 0 PAGES: 19

									SAIF DITA Project Strategy
12/27/10 (by Karen Smith)



SAIF DITA PROJECT STRATEGY
Contents
DITA Project Goals ........................................................................................................................................ 3
Why Use DITA?.............................................................................................................................................. 3
SAIF Book Requirements ............................................................................................................................... 3
  SAIF DITA Project Tools ............................................................................................................................. 4
     Tool Recommendations ........................................................................................................................ 6
     PDF Rendering Software ....................................................................................................................... 6
SAIF DITA Outline .......................................................................................................................................... 6
  SAIF Book Structure .................................................................................................................................. 7
  SAIF Topics - Organization ........................................................................................................................ 7
  SAIF Topics - Reuse ................................................................................................................................... 8
  SAIF Topic Owners .................................................................................................................................... 8
  DITA Topic Types ....................................................................................................................................... 8
  Topic Links ................................................................................................................................................. 8
Style Guide .................................................................................................................................................... 9
Graphics ........................................................................................................................................................ 9
  Visio and Enterprise Architecture Graphics ............................................................................................ 10
  PowerPoint Graphics .............................................................................................................................. 10
  SVG Graphics ........................................................................................................................................... 10
Concept Maps ............................................................................................................................................. 10
  XTM Topic Maps...................................................................................................................................... 11
Audience of the SAIF Book .......................................................................................................................... 11
  Executives ............................................................................................................................................... 11
  Architects ................................................................................................................................................ 11
  HL7 Work Groups .................................................................................................................................... 11
  Implementers .......................................................................................................................................... 11
SAIF Release Levels ..................................................................................................................................... 11
Review Strategy .......................................................................................................................................... 12
  Informal Reviews .................................................................................................................................... 12
  Formal Peer Reviews............................................................................................................................... 12
     Post-Peer Review Work ...................................................................................................................... 13
     Peer Review Plans ............................................................................................................................... 13
Output Formats........................................................................................................................................... 13
Where to Publish the SAIF Document ........................................................................................................ 14
Training and Knowledge Transfer Material ................................................................................................ 14
SAIF Content Management ......................................................................................................................... 14
  Filename Conventions............................................................................................................................. 14


                                                                                                                                                                 1
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

     Filename Conventions for SAIF DITA Topics ....................................................................................... 14
     SAIF Directory Structure...................................................................................................................... 15
     UUIDs for DITA Filenames ................................................................................................................... 15
   Long-Term Content Management Goals ................................................................................................ 15
     Evaluation of Alfresco with Componize and XDocs by Bluestream .................................................... 16
   Content Management Spreadsheets ...................................................................................................... 17
   Metadata Conventions ........................................................................................................................... 17
Joint SAIF/NCI Writing Project .................................................................................................................... 17
     ECCF Training Materials ...................................................................................................................... 17
     ECCF Implementation Guide ............................................................................................................... 17
Additional Questions................................................................................................................................... 18
SAIF DITA Design Summary ......................................................................................................................... 18




                                                                                                                                                        2
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)




DITA Project Goals
The 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 Requirements
The 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 Strategy
12/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 Tools
The 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


                                                                                                               4
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

       A robust DITA editor such as oXygen for DITA authoring
       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/



                                                                                                           5
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

       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)
       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 Recommendations
After 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 Software
Creating 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 Outline
Karen 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.

                                                                                                            6
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

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.

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

    1.    Executive Overview
    2.    SAIF Overview
    3.    SAIF Introduction
    4.    Enterprise Conformance and Compliance Framework (ECCF)
    5.    Governance Framework
    6.    Behavioral Framework
    7.    Information Framework
    8.    SAIF Implementation Guide (includes HDF, Facilitator’s Guide and Handbook)
    9.    Practical and Operational Perspectives of SAIF tutorial
    10.   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 - Organization
The 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.

                                                                                                            7
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)



Each topic covers some or all of following content:
    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 - Reuse
Currently, 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 Owners
Each 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 Types
DITA 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 Links
One 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:




                                                                                                         8
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

       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.
       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 file
             o 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 Guide
Karen 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.


Graphics
The 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).




                                                                                                            9
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

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 Graphics
Recommendation: 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.

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 Graphics
If 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 Graphics
Some 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 Maps
To 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.


                                                                                                         10
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

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 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.


Audience of the SAIF Book
The 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.

Executives
The executives would read the executive overview and the SAIF overview.

Architects
Architects 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 Groups
HL7 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.

Implementers
The 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 Levels
The SAIF book is updated periodically, as new material is written and existing material is revised.



                                                                                                           11
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

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:

       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 Strategy
The 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 Reviews
During 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 Reviews
In 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.

                                                                                                         12
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

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.

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 Work
After 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 Plans
The 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 Formats
The 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.




                                                                                                       13
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)


Where to Publish the SAIF Document
The 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.


Training and Knowledge Transfer Material
Karen 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 Location
DITA Processing paper     http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/dita_training_
and style guide           materials/DITA_PROCESSING_PAPER.docx
DITA Required Reading     http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/dita_training_
List (self-study)         materials/DITA_Required_Reading_List.docx
DITA training materials   http://gforge.hl7.org/gf/project/saeaf/docman/?subdir=305




SAIF Content Management
The 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 Conventions
The 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 Topics
Each 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.




                                                                                                         14
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

SAIF Directory Structure
The 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
     saif_archived_builds
     saif_output_builds
           saif_html_builds
           saif_pdf_builds
           saif_word_builds
     saif-dita-source-files
     <various top-level .dita files, SAIF.ditamap, SAIF.ditaval>
           bf
           customized_files
           eccf
           gf
           glossary
           graphics
           iguide
           infof
           intro
           saifex (doesn’t exist yet)
     saif-graphics
           finished_graphics
                 new_graphics
                 resized_for_builds
                      html_graphics
                      pdf_graphics
                 vector

UUIDs for DITA Filenames
In 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 Goals
Eventually, (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

                                                                                                           15
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

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:

       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 Bluestream
We 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)


                                                                                                        16
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

Content Management Spreadsheets
Available 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_version
        ing.xlsx.)
       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_workflo
        w.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_metadat
        a_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_DITA
        Files.xlsx.)
       Spreadsheet for tracking the graphics work (See
        http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/cms_spreadsheets/_Allgraphicsfil
        es_in_DITAfiles.xlsx.)
       Metadata conventions. (See
        http://gforge.hl7.org/svn/saeaf/trunk/docs/saif_edit_project/Editing_project_docs/saif_metada
        ta.xlsx.)

Metadata Conventions
Metadata 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 Project
Jane Curry is coordinating the joint SAIF/NCI writing project. We are working with NCI on a common
design strategy for the documents.

ECCF Training Materials
A 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 Guide
The 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.


                                                                                                         17
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)


Additional Questions
    1. 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.
    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 Summary
This 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            Spreadsheets
management



                                                                                                      18
SAIF DITA Project Strategy
12/27/10 (by Karen Smith)

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
                             host the SAIF DITA document on the HL7 web site.

Translation into other       None at this time
languages

Content reuse                Yes, where applicable




                                                                                                    19

								
To top