_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: [email protected]
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.
Top Related