1

SAIF DITA TrainingFall 2010

2

Part I – Introduction to DITAObjectives◦Learn about DITA◦Set up your DITA environment◦Become familiar with the oXygen interface

3

Part 1.1 – Learn about DITAWhat is DITA?Benefits of using DITAChallenges of using DITASAIF DITA strategy and goals

4

DITA overviewDITA is an XML-based architecture for

creating topic-oriented, information-typed content that can be reused and single-sourced in a variety of ways.

DITA is an extensible architecture that allows creating new information types and specialized elements.

5

Benefits of using DITATopic-based authoring

6

Benefits of using DITATopic-based authoringConsistent look and feel

7

Benefits of using DITATopic-based authoringConsistent look and feelPublishable in many output formats

8

Benefits of using DITATopic-based authoringConsistent look and feelPublishable in many output formatsEasy to restructure table of contents

9

Benefits of using DITATopic-based authoringConsistent look and feelPublishable in many output formatsEasy to restructure table of contentsContent reuse

10

Benefits of using DITATopic-based authoringConsistent look and feelPublishable in many output formatsEasy to restructure table of contentsContent reuseInteroperability and portability

11

Benefits of using DITATopic-based authoringConsistent look and feelPublishable in many output formatsEasy to restructure table of contentsContent reuseInteroperability and portabilityCustomizable (filtering of information)

12

Challenges to using DITAMoving from Word to DITA

13

Challenges to using DITAMoving from Word to DITALearning curve

14

Challenges to using DITAMoving from Word to DITALearning curveChallenge of converting legacy docs

15

Challenges to using DITAMoving from Word to DITALearning curveChallenge of converting legacy docsEasy to create output but difficult to

customize w/o scripting knowledge

16

Challenges to using DITAMoving from Word to DITALearning curveChallenge of converting legacy docsEasy to create output but difficult to

customize w/o scripting knowledgeHandling images in different output formats

17

Challenges to using DITAMoving from Word to DITALearning curveChallenge of converting legacy docsEasy to create output but difficult to

customize w/o scripting knowledgeHandling images in different output formatsDeciding which DITA template to use for

specific material

18

SAIF Documentation – Paper based

19

SAIF Documentation – DITA based

20

Short-term goals of the SAIF DITA project

Convert the SAIF documents from Word to DITA.

Compile a SAIF “book” using DITA. Publish the book to the HL7.org web

site.

21

Long-term SAIF DITA strategySet up a common, shared infrastructure

for future maintenance of the SAIF material.

Make the SAIF DITA document available to other HL7 work groups and organizations working on related projects.  

If the SAIF DITA project is successful, HL7 will be more likely to use DITA for other projects.

22

Part 1.2 - Components of a DITA project

Ditamap filesDITA topic filesGraphics files

23

DitamapsA ditamap organizes the topics in a DITA

document.A ditamap can include other ditamaps.You can specify a relationship table of

links in a ditamap file.

SAIF master ditamap

Sub-ditamaps within the master ditamap

SAIF introduction ditamap

26

Ditamap templatesDitamap type DescriptionDitamap Use this ditamap template for all output

formats.

Bookmap Use this ditamap template for publishing books.

Learning ditamap Use this ditamap template for training documents.

Learning bookmap Use this template for training books.

Eclipse ditamap Use this ditamap template in an Eclipse-based help system.

Subject scheme Use this template to create a DITA subject scheme.

27

What is a DITA topic?A topic is a discrete piece of content

that is about a specific subject, has an identifiable purpose, and can stand alone.

Each DITA topic is normally in its own file.

A large DITA project can have hundreds of topic files.

28

DITA topic templates (1)DITA provides templates for different

types of topics.The SAIF book uses the following topic

types:◦Concept◦Reference◦Generic topic◦Glossterm

29

DITA topic templates (2)Topic type Description

Composite Use for content references.Use for complex topics that include conceptual, task, and reference information.

Concept Use for explaining concepts and narrative material.

Generic topic Use for topics that do not fit into the other categories, or for transitional topics.

Glossterm Use for glossary entries.

Reference Use for lookup tables, graphics, examples, and other data.

Task Use for procedures.

General task Use for procedures (more flexible structure).

30

DITA topic templates (3)If you are writing a training document,

DITA provides 4 learning topic types:◦Learning assessment◦Learning content◦Learning overview◦Learning summary

31

DITA examplesThe next few slides show examples of

the different types of DITA topics.

SAIF concept topic example

SAIF reference topic example

Task topic example

SAIF glossterm topic example

36

Part 1.3 – Setting up your DITA environment

37

Set up your DITA environment1. Install and configure oXygen.2. Set up your source file directories.3. Ensure that you have permissions to

SVN for http://gforge.hl7.org/svn/saeaf/trunk/docs/saeaf-dita/.

4. Learn the oXygen interface and menu commands.

38

Installing and configuring oXygen Download & install oXygen from

http://www.oxygenxml.com/download_oxygenxml_editor.html.

See Wilfred Bonney for the license key. The oXygen license is name based, so

you can install it on as many computers as you use.

39

Set up your source file directories Check out the DITA source files from

http://gforge.hl7.org/svn/saeaf/trunk/docs/saeaf-dita/saif-dita-source-files/.

Copy these files to another location on your computer. When you are finished updating your DITA files, validate the

SAIF ditamap. Copy the files back to the checked out SVN directories. Commit these files at least weekly. Create an output directory for storing DITA output. Back up the DITA files stored on your computer. Coordinate work with others who might be working on DITA

files from the same SVN directory to avoid overwriting each other’s changes.

40

Transferring the oXygen license1. To remove the oXygen license, delete the

license.xml file from the home folder on your computer.

2. It is not necessary to uninstall the oXygen application if you want to preserve it until you need it again. When needed again, you can start oXygen and re-enter the license key.

Windows 7 -C:\Users\(Admin)\AppData\Roaming\com.oxygenxml\license.xml

The oXygen interface

42

Author view (main window) Shows the DITA topic that you are editing or writing

43

Grid view Displays grid structure (useful for working with

tables and databases)

44

Text view Displays the source XML code

45

Outline viewShows the DITA tags and displays the structure

of a DITA document

46

Displaying DITA tagsFull tags with attributes <fig id="bf_transactions" frame="topbot">Tags <fig> (shows all tags w/o attributes)Block tags <fig> (paragraph level)Inline tags (text level)Partial tags (triangles show styled text)No tags (looks like Word)

Demo #1 Take a tour of the DITA functions in

oXygen

48

Part I SummaryYou have:◦Learned about DITA◦Set up your DITA environment◦Become familiar with the oXygen interface