_experience the commitment TM

Migrating to DITAPresenting the PAS Knowledge Base

Karen Lowe

May 17, 2007

© CGI GROUP INC. All rights reserved

2

Agenda

• Context• Move from RoboHelp• Choice of DITA• Migration process• Results

3

The CGI Context

CGI’s product:Production Accounting Solution

CGI’s issue:We want our Web application to last ~20 years. We also want the help to work for that long, too, regardless of browser issues.

4

A PAS Screen

5

Putting the Situation in Context

The year: 2006

The tool: RoboHelp X5

The industry issue: Adobe purchased Macromedia and was ominously silent on any upcoming development on RoboHelp. It was unknown if RoboHelp would support the changes around Vista operating system and IE 6.

= Uncertainty

6

Tech Writers’ Real Issues

• Managing information in and between projects• Creating consistency• Ensuring accuracy

• Processing information • Creating content• Reusing content

• Delivering information• Publishing Help• Creating whitepapers/pdfs/guides

The Move from RoboHelpLimitations of traditional tools

8

Traditional Tools

Plus Side• Small learning curve• Generate Help files or print

output• Can convert info to other

format(s) (but can be painful)

Negative Side• No cross project/product

capabilities• Limited reuse ability• Limited print/PDF output• Limited ability to create

interactive user assistance• Cost

9

Changing the Perspective

Our Finding:

We need to change our process.

The Move to DITA

11

Goals:

• Update our way of thinking about information:• XML and DITA• Object Oriented approach • Content vs. Delivery

• Focus on accessible User Assistance:• Embedded links to information• Consistency• Access varies with context

12

Why XML and DITA?

XML • Non-proprietary, readable, accessible• Object oriented

DITA Open Toolkit• Darwin Information Typing Architecture, an open source

set of DTDs, schemas and output capability• Standardized framework/architecture for creating technical

documentation

13

Object-Oriented Content

• Information created and managed as modular chunks (topics)

• Topics are the building blocks of information products

14

Control the Content & Output Separately

topic

concept task reference

• Tagged content• Structure based on content

• Concept, task, reference topics• Build output based on Maps• Look of output depends on transformations and stylesheets

15

Sample Topic in Help

16

Sample DITA Code in Eclipse

17

Accessible User Assistance

• Back to standard questions:• Who uses a Help system?• What are they looking for?• Why are they looking for it?• How do they find it?

18

Who?

• Beginners new to the job/task• Beginners new to this system• Users faced with a new task (beginner, intermediate or expert users)

• Users who forget details on a specific task (beginner, intermediate or expert users)

19

Why?

• I want to know:• How to do a task• What parameters a field/screen needs• Understanding the concepts of the system• Understanding a complete task/process• Introductory material• Access to other reference• Training

20

What?

• I’m happy when:• I can complete my task• I understand the whole process• I can perform the entire process• I can enter data in a field/screen without errors• I understand why the system is doing what it’s doing

• I can find answers

21

How?

• Bottom up (application to Help file)• Field level• Screen level• Task level

• Top down (Help to application)• Concepts• Tasks• Reference• Training

22

Embedded Help – Bottom Up Approach

23

Help – Top Down Approach

Migration

25

The Process We Took To Get Here:

• Tool evaluations• Proof of Concept • Analysis• Migration• New Content Updates

26

Step 1: Tools Investigation

• Analysis of our requirements• DITA Open Toolkit

• Resources, assistance

• XML Editors:• XMetal• oXygen

• Framework:• Eclipse• ANT scripts

• CMS (future)

27

Step 2: Proof of Concept

• Get DITA OT up and running• Learning curve• Many, many technical issues

• Usability of a Help System• Learn more about our users• Requirements gathering

• Move to structured writing and unified approach• Reuse content• Classification of content

28

Step 3: Analysis

• Content• Needed/not needed• Reuse opportunities• Link structure

• Audience• Level of knowledge

• Output• Help• FAQ• Future items, such as Guides, Training material

29

Step 4: Migration

• Manual Labour• Combined migration with analysis

• Best practices • On-going process of learning

• Decision document• Project document

30

Step 5: New Content

• Keeping up with development• Reusing where possible• Generating different output

31

Learnings

• More analysis = less exceptions and greater reuse• But beware of analysis paralysis!

• Create an info model, including an approach for reuse

• Establish and follow standards and conventions• Determine naming conventions, content assemblies and

content topics• Plan on using structure, templates • Minimize specialization, if possible

Other ConsiderationsorHow this became more than just a Help file

33

Navigation Strategy

• Turned the highest classification level into tabs

34

Consistent Cues for Finding Info

• Predictable linking strategy• Coloured links (CSS)• Used relationship tables

and maps in DITA

35

Access to External Content

• Banner in the CSS contains links:• Industry information• Release Notes

36

Custom Content

• Issues:• My company says we have to do something one way. How

can we see that detail?• I found a ‘gotcha’ in the process. Where can I write that

down so others don’t make the same mistake?• Solution:

• Company-Specific Information Wiki:• Editable by clients• Stored outside of the Help• Maintained by clients outside of Help

37

Sample

• Installation parameter• No security/monitoring by CGI

38

Help on Steroids

• Issues:• Everyone is a new user• We only have one physical Training Instructor

• Solution:• Capture common training information

• Multimedia• Not a Learning System• Repeatable solution• High-level content pertinent to all users

39

Sample – Training Video

40

Sample – Screen Demo

41

Future Work

• Incorporate a CMS• Further define workflow• Automate areas, such as map generation• Use metadata• Generate Documentation On Demand

Results

43

Embedded Help Avoids Problems

• Accessible• Extensible• Right amount of information at the right time

• Info is appropriate to the access level • Limit content to one option• Link to other content

44

Reuse Is WONDERFUL

• Consistency between topics • Less rewriting of content• Change isn’t a 4-letter word

45

Clear and Predictable Organization

• Simplified approach • Task, concept, reference via application and tabs• Unified colour usage

• DITAmaps and relationship tables control links

46

Benefits of a Better Help System

• A comprehensive Help system empowers users• They can find their own answers• They can add their own information• They can link to other resources

47

A Good Help System Saves Money

• Reduced reliance on Help Desk• The calls that do come in are less mundane= more interesting for the Help Desk

• Reduced calls saves Help Desk $$ and time

48

A Good Help System Equates to Goodwill

• Increase usability of the application• Client satisfaction

(translation: CGI is trying hard to meet my needs…)

Thanks for coming!

Questions? You can contact me at: karen.lowe@cgi.com

What challenges do you face?

If you could deliver anything, what would you include?

_experience the commitment TM

our commitment to youWe approach every engagement with one objective in mind:to help clients win and grow.