fico’s journey to dita: the shift from unstructured framemaker to dita and beyond

Confidential. This presentation is provided for the recipient only and cannot be reproduced or shared without Fair Isaac Corporation's express consent.

© 2010 Fair Isaac Corporation. 1

FICO’s Journey to DITA The Shift from Unstructured FrameMaker to DITA and Beyond

Kathryn Mellos Mahoney Technical Publications Senior Manager FICO

February 24, 2012

© 2010 Fair Isaac Corporation. Confidential. 2 © 2010 Fair Isaac Corporation. Confidential. 2

Agenda

» The Problem

» The Solution

» The Shift

» Current Results

» Next Steps


―It’s not that I’m so smart, it’s just that I stay with problems longer.‖

Albert Einstein

The Problem

© 2010 Fair Isaac Corporation. Confidential. 4

The Journey Started Long Before FICO

» 1997—Word and RoboHTML

» Globalink Power Translator Pro and Simply Translating User’s Guides and Help » The two products share much of the same code, the latter including a

subset of the former’s features.

» 2000—More Word and RoboHelp

» HNC Falcon Fraud Manager Credit and Debit Data Specifications » The two documents are largely the same, with identical feed layouts but

different valid values and definitions based on the market.

» 2004—Unstructured FrameMaker

» Fair Isaac Falcon Fraud Manager Credit and Debit Data Specifications, for UNIX and Mainframe » The four documents have the same problem as before, but conditional text

alleviates some of the superficial problems.

» 2009—XMetaL with SDL Trisoft Bridge

» FICO...Same Data Specifications, Data Dictionary and Database Reference » Five documents created using Excel spreadsheets converted into DITA

topics with conditional text via Python scripts.


The Destination

I need to get the best reuse, the most flexibility, and the greatest consistency out of my topics.

I want to do the work once and have it affect all of my deliverables.


―Focus 90% of your time on solutions and only 10% of your time on

problems.‖

Anthony J. D’Angelo

The Solution


Why Did the Executives Choose DITA?

» Significant translation savings

» Automation: Efficient scripting, build integration achieved

» Flexible deliverables: PDF, Eclipse Help, platforms, re-branding

» Reuse: Fewer writer/reviewer resources, early consumption by next product, localization readiness, cost savings.


What Did the Managers Think?

» ―YAY! REUSE!!!‖

» ―Be careful what you wish for...‖

» ―We will need training.‖

» ―This will be a challenge.‖

» ―How can I manage people through the change?‖

» ―I hope I don’t lose people because of this.‖


What Did the Writers Think?

» ―I like the tools we have.‖

» ―This looks too hard.‖

» ―I want to have control over the layout.‖

» ―The templates are too rigid.‖

» ―It will take longer for me to do my job.‖

» ―We don’t need it.‖

» ―We won’t have more than one person working on a single book.‖

» ―Our books are fine as they are.‖


―With great power comes great responsibility.‖

Thomas Francis Gilroy

The Shift


The Journey Begins in Earnest— DITA Implementation Timeline

» DITA/XMetaL training

» Workgroups develop essays to

find a common understanding

of their areas. Identify key

terms.

» Develop context-sensitive Help

delivery mechanism with

Common Components group

» Begin DITA department

standards, templates, output

scripts

» Committee charters, team

sites, communication

processes

» Initial issues lists, plans

» DITA conversion of usable

legacy documentation started

(used localization budget from

savings in DITA)

» Finalize Trisoft configuration

» Develop and document

department DITA standards

and procedures

» DITA Authoring Guide–

XMetaL and element usage

» Base DITA templates and

reusable components

» Initial writing style and

process guidelines checklist

» Initial DITA output scripts for

PDF in FICO ―look and feel‖

» Plan and develop common

topics –Content Specs

» Glossary terms

» Workgroups

» Trisoft Component Content

Management System

» Production environment ready

» Train department members

» DITA Authoring Guide–Trisoft

» Develop and review product-

specific and common topics

» Combine common and product

topics into deliverables for review

» Develop InfoCenter delivery

mechanism with Common

Components group

» Customize Antenna House for

Eclipse Help publication

» Topic automation via SDL Trisoft

API for data formats and

descriptions in Excel

» Finalize output scripts for PDF,

Help

»Final Falcon docs in review

»DITA Training

Q1, 2009 Q3, 2008 Q4, 2008

»Common and product topics

»Processes involving other departments

»Trisoft CMS in production

»Design

DITA processes

»Trisoft CMS setup

»Common Help component

»Combine topics

»InfoCenter

» Lessons learned: You can’t think through all of the problem details before you start. If you spend too much time up front speaking in generalities and predictions, you will have wonderful conversations that may have little to do with the practical nature of your information.


The Journey Continues— Feature Implementation Timeline

» First release of deliverables

using DITA.

» Opportunity to reinvent the

documentation set with

Falcon 6.0.

» 40% of the documentation

set in DITA; focus on the

highest level of reuse.

» Introduce Python scripts.

» Reuse a common appendix

for Contacting FICO.

» Agree on a common set of

variable libraries, three levels

deep.

» XMetaL—Table macros

» Common topics for Case

Manager.

» Lessons learned: You don’t

have to do it all in one

release. Add complexity as

you master each skill.

» 100% of the documentation set

in DITA.

» Start freezing the publication

baselines or using source-

control management to archive

deliverable source.

» Send remaining FrameMaker

documents to the vendor for

conversion.

» Add simple conditional text.

» Lessons learned: It is

important to have your work

under source control so that

you can duplicate or tweak

books based on their final

published state.

» Tools upgrade.

» Start Insurance Fraud Manager

documentation in DITA.

» Convert existing FrameMaker

documents with third-party vendor.

» Start with high reuse documents.

» Second complete doc set in DITA.

» Synchronize book introductions.

» Introduce Context References

(conrefs) for overview topics that

have a high level of reuse.

» Add more Python scripts.

» Lessons learned: Get it in DITA,

then synchronize the topics.

»Second full doc set released in DITA

»First partial release in DITA »Second release in DITA—

Full doc set

»Tools upgrade

Q4, 2009 Q2, 2009 Q3, 2009

»Second product in DITA


Features Continue to be Added with Each Release…

»Customized placeholder topics

»Localization

1H, 2010 H2, 2010

»Add reltables

»Maximize screenshots

»Increase reuse across products

» Use placeholder copyright text to create custom

copyright files.

» Clean up UIElements, variables, etc.

» Add Relationship Tables (reltables)

» Add AuthorAssistant (terminology facilitator)

» Lessons learned: Do not use XML cross

references in topics. When they are used by

another publication that does not include the

topic, the links will break.

» Focus on Localization

» Considerations around screenshots. Use variables,

conditional text, or different topics?

» More products using the same topics.

» More conditional text.

» Lessons learned: Use conditions on entire

sentences, not phrases within sentences. Be

consistent with variable usage and stringing variables.


…as our Expertise Grows.

» Introduce Context References (conrefs) for

system requirements. Create once and use in five

deliverables with two different formats.

» More information architecture. Sharing maps

across products and workgroups

» Lessons learned: Just because you can reuse

something, does not mean you should.

» Use a common copyright topic.

» Common organization for book types.

» Lessons learned: Just because something is

different, you don’t have to create a new topic.

»System Requirements conrefs

»Common copyright topic

1H, 2011 H2, 2011

»Add more Information Architecture

»Common deliverable

elements


―I believe that if you show people the problems, and you show them

the solutions, they will be moved to act.‖

Bill Gates

Current Results


Where we are…..

» Reuse exceeds 25% projection

» Falcon Fraud Manager—73%

» Insurance Fraud Manager Installation Guide—90%

» We have robust publications, rich with shared topics, conditional text, reltables, graphics, conrefs, and variables.

» Our output is consistent and reliable. Our centralized production allows for no lag time for updates.

» Our publications are being translated.

» Our tools provide us with quick access to previous versions of individual topics and publications.


―It is not unreasonable that we grapple with problems….Our

responsibility is to do what we can, learn what we can, improve the

solutions, and pass them on.‖

Richard P. Feynman

Next Steps


…and Beyond

»DITA with Agile »New delivery methods

2012

»Adoption in other groups »Additional tools

» Use DITA in an Agile Environment.

» Explore DITA adoption in Development, Education, Scoring.

» Pilot XOpus/LiveContent.

» Reuse our DITA topics to deliver information in different methods.

» Create a richer and more defined experience for user assistance. Link to other media, including:

» user forums

» video tutorials

» examples

» knowledge bases

» real-time feedback on documentation

» receive documentation updates


―The message from the moon…is that

no problem need be considered

insolvable.‖

Norman Cousins

Confidential. This presentation is provided for the recipient only and cannot be reproduced or shared without Fair Isaac Corporation's express consent.

© 2010 Fair Isaac Corporation. 20

THANK YOU

February 24, 2012

Kathryn Mellos Mahoney 858-369-8445 [email protected]

fico’s journey to dita: the shift from unstructured framemaker to dita and beyond

Technology