![Page 1: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/1.jpg)
Structured FrameMakerWhat a Long, Strange Trip It’s Been!
Walter Hanig & Sarah O’KeefeMar. 14, 2007San Diego STC
![Page 2: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/2.jpg)
Coming attractionsCase studyWhither Teradata?What about the industry?“And I care because why...?”
![Page 3: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/3.jpg)
Initial project objectives
Define, implement consistent content organization, print and onlineReduce back-end processing for PDF, helpSimplify infrastructure (fewer templates, fewer tags)Move toward explicit information modelingExploit off-the shelf products and experienced consultants
![Page 4: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/4.jpg)
Business case?
Cost reduction from localization makes an easy justificationConsistency, yes. But whoseconsistency?
“Exploit”??
![Page 5: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/5.jpg)
Timeline
Concept (Single-Sourcing) Mar-02Concept (Structured Frame) Sep-02Contract Apr-03Sample conversion Aug-03Training Nov-03Initial conversions Nov-03Final conversions Jun-04Deliveries from FM7 Nov-04Contract end Dec-04
![Page 6: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/6.jpg)
Six months. Or more.
Almost impossible to implement in less than six monthsTwo years not at all uncommon, especially for government customers, where the funding is tied to fiscal yearsConsider a phased implementation
![Page 7: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/7.jpg)
Results
One size fits all EDD• Much use training required
Successful deliverables beginning 11/04Continuing, but dwindling updates to EDD, templatesAwareness of need and value of information and document modelingPartial understanding of semantic labeling instead of visual tagging
![Page 8: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/8.jpg)
Challenges (1)
Organizational culture• Distinct internal organizations; mistrust• Consensus-based management
CHANGE!Project management changesLack of local management buy-inCHANGE!
![Page 9: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/9.jpg)
Challenges (2)Investor-beneficiary disconnectLack of style guide and information modelsCHANGE!Limited technical expertiseNot invented here“But presentation matters!”Conflicting visions on route to goal
• Good enough• Match existing output
It’s not Information Mapping!Legacy documentation problems
![Page 10: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/10.jpg)
The challenge of legacy documentation
Death with dignity?Migration cost can be easily more than cost of implementation itself• Tables inside tables...
Rewriting cost can be easily...well, you get the ideaCan you triage?
![Page 11: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/11.jpg)
Viva la Resistance!
If your implementation doesn't meet writers' real needs, resistance is an appropriate response• Don't implement garbage• Do pay attention to requirements for
your particular workflow• Do not allow vendor marketing to
drive your decision process
![Page 12: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/12.jpg)
It's all about the people.
Change resistance very commonCompetition between departments problematicHow do you sell to your own organization?Strong leadership required; expect turnover
![Page 13: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/13.jpg)
Post-mortem, bono (1)Hired contractor• Element definition document (EDD) and related
infrastructure• Conversion of legacy documentation• Training• Consulting
Developed in-house expertise• EDD/structured FrameMaker• WebWorks Publisher• FrameScript• Extensible Stylesheet Language (XSL)
![Page 14: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/14.jpg)
Post-mortem, bono (2)
Met deliverable commitmentsNo loss of qualityAwareness of semantic taggingProductivity gains from single-sourcing
![Page 15: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/15.jpg)
Post-mortem, mal
Reinforced internal distrustAvoided discipline issuesOutstanding change requests
![Page 16: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/16.jpg)
Post-mortem @ Scriptorium
No clear authority figure (“Decider”) inside client organization.Not possible to develop consensus between hostile groups.Unwillingness to compromise.Lack of maturity in existing writing process.
![Page 17: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/17.jpg)
Levels of authoring1. Ad hoc writing. No resemblance
between documents.2. Similarities on paper, but
implementation in files different.3. Template-driven authoring with minimal
overrides.4. Structured authoringTeradata was a 2+. Difficult to jump to 4.
![Page 18: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/18.jpg)
Success Factors (1)
Buy-in: why is this change• Necessary?• Valuable to the company?• Valuable to the individual?
Well-defined templatesClear management structure, responsibilitiesDedicated, authorized project manager
![Page 19: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/19.jpg)
Success Factors (2)
Programming expertiseFocus on content; minimal interest in presentationOpenness to mistakesProcess-orientationOvercommunicationPilot project
![Page 20: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/20.jpg)
Success factors
![Page 21: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/21.jpg)
Failure factors
No templatesNo information model• Book structure for user guides, reference
manuals, language references, APIsNo style guideNo trustNo decision-making process
![Page 22: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/22.jpg)
Failure factors
Open hostility among writing groupsNo bad cop. Not even a sheriff.Extreme change resistanceSome writers threatened by elimination of formatting (“tweaking”)?No previous template-driven authoring; culture shock
![Page 23: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/23.jpg)
Follow-on activities
Root cause investigation• User difficulties with overly complex EDD
Modeled information structure and needs• Designed for discovered use cases
Created simplified EDDCreated single-source PDF, HTMLMixed results
• Better use of EDD• Learned information modeling• Met some user expectations• End products not compelling to use• Stale, unreliable source information• Need to model content• Need to define topic maps
![Page 24: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/24.jpg)
What we're up to now
Development driven by business needsContent management pilot• Astoria Software• AntennaHouse
DITA• Externally defined DTD• Vendor-supported• “Specializable”
![Page 25: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/25.jpg)
DITA
Removes ownership issues from structureDoes it fit your requirements?Out of the box, faster implementation. With specialization, maybe not.Vendors like it
![Page 26: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/26.jpg)
Industry trendsShift away from print/PDF as primary deliverableNo really excellent XML solution (Big Three contenders: Arbortext, FrameMaker, XMetaL)Localization cost driving XML adoptionCraftsmanship versus object-oriented writingLots of excitement about DITA
![Page 27: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/27.jpg)
![Page 28: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/28.jpg)
Some inconvenient truths
You are not your audience.Your readers don't care as much as you do.Money matters.Resistance is futile.You are not as cute as a panda.Being a writer ain't enough.You have to become a different writer.
![Page 29: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/29.jpg)
New job opportunities
Information architectCMS administratorXSL programmer
![Page 30: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/30.jpg)
XML and your career future
XML is the Next Big Thing.Adapt or...ugh.XML/XSL provide options outside tech pubs. (Can you say “programmer salary”?)Learn about the concepts behind “structured authoring”Requires better writers to create context-neutral, topic-oriented content
![Page 31: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/31.jpg)
Contact information
Walter [email protected]
Sarah O'[email protected]
White paperswww.scriptorium.com/papers.html(free with registration)
![Page 32: Structured FrameMaker - Scriptorium · 2017-01-27 · Structured FrameMaker What a Long, Strange Trip It’s Been! Walter Hanig & Sarah O’Keefe Mar. 14, 2007 San Diego STC](https://reader034.vdocuments.net/reader034/viewer/2022042400/5f0edfb87e708231d4415be4/html5/thumbnails/32.jpg)
Q & A