Upload
steven-jong
View
267
Download
1
Embed Size (px)
DESCRIPTION
Is DITA/XML in your future? Have you heard rumors of an impending CMS? Or do you suspect these tools will be in your future sooner or later? Two veterans, Steve Jong and Anna Pratt, have moved from FrameMaker/Word/RoboHelp to XMetaL and, variously, Vasont CMS, Perforce, and Microsoft Team Foundation Server CMS. Steve and Anna describe the transition they underwent, expose the love-hate relationship you’ll develop with DITA, and share their insights about how to survive and thrive in an XML world.
Citation preview
Surviving Thriving in an XML WorldSteven Jong and Anna Pratt
04/11/2023
Overview1. Concepts: the differences between desktop publishing
and structured environments
2. Our Stories: converting existing material to a structured environment
3. Show and Tell: comparing and contrasting our work environments and processes
4. Survey Says: How Anna’s group feels about the change
5. Summary: How you too can survive—and even thrive! —in an XML world
6. Demonstration: making a change to a topic
Surviving Thriving in an XML World
To quote a wise man:
“Here’s my number. My company can help you when you’re ready to convert back…”
04/11/2023
What is Structured Information?
Structured information is information that has been analyzed, categorized by type, and organized
Compare with data typing
Intellectual-property implementation: Information Mapping®
Topics: concepts, tasks, references
Example: a step is part of a task (but not a concept)
Structure is separated from format
Commercial tools now support structured information
Surviving Thriving in an XML World
04/11/2023
What is DITA XML?
Darwin Information Type Architecture
eXtensible Markup Language (widely used)
One implementation of Structured General Markup Language (SGML)
Surviving Thriving in an XML World
04/11/2023
DITA AdvantagesImplements structured information
Readily supports reuse and reorganization
True single sourcing
CMS library uses database technology to support a secure, controlled, multi-user environment
Supports large, highly complex documents well
Supports conditionalization well
Integrated, automated workflow (where used)
The bigger the group, the bigger the library, the more topics are shared, the more translation done, the more channels… the better the case for DITA
Surviving Thriving in an XML World
04/11/2023
DITA DisadvantagesRigidly enforces both organization and structure
Very little control over format
Separation of steps in create/edit/produce process
Lots of do-it-yourself or open-source pieces
Requires dedicated support personnel for even small changes
Attention to detail by all team members is critical—one rogue actor can do real damage
Surviving Thriving in an XML World
Anna’s Awesome Adventure
Into the wild world of DITA and XML
Established company, using FrameMaker, Word, AuthorIT
Acquired by a larger company with dispersed doc teams, using FrameMaker, Word, RoboHelp, DocBook
Tech Comm team researched DITA and CMS system options and chose XMetaL and DITA as production tools
Consulting firm converted inaugural document set
Dispersed teams converted remaining docs
DITA + CMS =
Recently put a CMS in place (Team Foundation Server-TFS)
Migrated 90% of projects to CMS (based on product build systems)
Kept the other 10% in another source control system
Work Flows
Hierarchies
Checking files in and out
Opening 5 to 7 pieces of software
Favorite? Mistakes
Forgot to add topics to source control
Referenced a deleted topic
Worked with transforms (or not)
04/11/2023
Steve’s Stirring Story
Startup company, using FrameMaker/Word, Acrobat Pro
No online help
Acquired by larger company with a five-year-old DITA/CMS environment in place (and the scars to prove it)
New tools: Vasont CMS, XMetaL editor, Apache FOP
Existing documents converted into XML by a third-party vendor
Online help, but no translation
Surviving Thriving in an XML World
04/11/2023
What Worked Well (Steve)
Vendor successfully converted 6 books/1000 pages
Vasont and home-grown scripts incorporate many process steps
Main book has 3 modes; once converted, 1 click generates any of 3 output formats (including Help)
20 writers maintain a CMS library of 700 books, 50,000 topics
Surviving Thriving in an XML World
04/11/2023
What Didn’t Work Well (Steve)
Neither seamless nor transparent
Considerable manual cleanup (that I couldn’t let go)
One topic was 100 pages, formatted as a glossary; subsequently split (manually) into ~100 reference topics
The new work environment uses remote connection; can’t copy/paste from spec to topic
Generating output can take 30 minutes
Surviving Thriving in an XML World
04/11/2023
Steve’s Development Process
Surviving Thriving in an XML World
Survey Says…About the transition…
Works Well
All teams use the same tools
Documented DITA standards and processes put every team on the same boat… (which only feels like it’s sinking)
Reusability is much easier
Conditional text expands content capabilities
Content tagging for localization
Agile Development Environment
Pain PointsTransition process: getting content from the source tool to XML tool
Identifying topics to share
Choosing the topic type
Shortcuts
Content tagging for localization
Finding information in the source
04/11/2023
Working From a Distance
Surviving Thriving in an XML World
04/11/2023Surviving Thriving in an XML World
04/11/2023
Pace
Surviving Thriving in an XML World
04/11/2023
Structure Begins in Your Mind
Focus narrowly
Look for concepts, tasks, and references (and name them that way)
Keep everything simple
Look for opportunities to share
Stick to the style guide!
Don’t repeat—reuse
… But don’t push sharing too far
Don’t use formatting to indicate structure
Don’t mix concept, task, and reference material in a topic
Don’t write lists as sentences (and learn to accept one-item lists)
Surviving Thriving in an XML World
04/11/2023
Converting Existing Documents
Format is not structure
Don’t expect too much from automated conversion
Blended material (concept + task + reference) can’t be categorized, so you will have to rewrite it
Surviving Thriving in an XML World
Decide on the workflow and file structure/hierarchy
Plan your transition schedule
Budget time and money for ongoing maintenance of your DITA system
Plan to have someone on staff familiar with XMLT, DITA
Get buy-in from all writing teams
Make everyone aware of the benefits and the limitations of DITA
Surviving
Let it go…Ownership
Format controlPage breaks
Heading/footer navigation for the user
“Keep with next”
Tables with no continued titles
Quality control
Personal preferences and opinions (even if you’re right!)
To quote a wise woman
“…although our local team had some 150 years of collective tech writing experience,
our DITA deliverables reflect intern-level quality at best.”
Thriving
Become familiar with DITA, XML, and .bat files
Figure out the best way to use ditavals and variables
Learn to love F11 to go from this:
To this:
04/11/2023
Thrive on…
Discover the joy of reading log files and code
NEVER lose your sense of humor!
Surviving Thriving in an XML World
04/11/2023
Demonstration
Making a single change to a topic
1. Extract topic from CMS library
2. Edit topic
3. Upload topic into CMS library
4. Render document (as PDF)
Surviving Thriving in an XML World
04/11/2023
Extract: Book Map
Surviving Thriving in an XML World
04/11/2023
Extract: Navigator
Surviving Thriving in an XML World
04/11/2023
Extract: Local Folders
Surviving Thriving in an XML World
04/11/2023
Edit: Normal View
Surviving Thriving in an XML World
04/11/2023
Edit: Tags On View
Surviving Thriving in an XML World
04/11/2023
Edit: Text View
Surviving Thriving in an XML World
Edit: Raw View<?xml version="1.0" encoding="utf-8"?><!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN" "http://cmsrender01/dtd/task.dtd" [<!ENTITY cbl "cable”><!ENTITY wln "wireline”><!ENTITY wls "wireless”>]><?VasontExtractInfo entity_id="4164257" version_id="11883"?><task id="t_cmp_wireless_usr_managing_network_elements_creating_a_network_element_group"><title id="v4000867">Creating a Network Element Group</title><prolog id="v5356143"><metadata id="v5356144"><keywords id="v4000871"></keywords></metadata></prolog><taskbody id="v4000872"><context id="v4000873">To create a network element group:</context><steps id="v4000876"><step id="v4000877"><cmd id="v4000878">From the <uicontrol id="v4301940">Network</uicontrol> section of the navigation pane, select <uicontrol id="v4000879">Network Elements</uicontrol>.</cmd><stepresult id="v4256868">The content tree displays a list of network element groups; the initial group is <uicontrol id="v4000881">ALL</uicontrol>.</stepresult></step><step id="v4000882"><cmd id="v4000883">From the content tree, select the <uicontrol id="v4000884">ALL</uicontrol> group.</cmd><stepresult id="v4256870">The Network Element Administration page opens in the work area.</stepresult></step><step id="v4000887"><cmd id="v4000888">On the Network Element Administration page, click <uicontrol id="v4000890">Create Group</uicontrol>.</cmd><stepresult id="v4256872">The Create Group page opens.</stepresult></step><step id="v4000892"><cmd id="v4000893">Enter the name of the new network element group.</cmd><info id="v5040534"><ph id="v5040535" otherprops="pr_215419"> The name can be up to 255 characters long and must not contain quotation marks (") or commas (,).</ph></info></step><step id="step_5C4171AF06904E3D8FE7C244CD094C8D"><cmd id="v4286870">Enter a text description of the network group.</cmd></step><step id="v4000896"><cmd id="v4000897">When you finish, click <uicontrol id="v4000898">Save</uicontrol> (or <uicontrol id="v4000899">Cancel</uicontrol> to discard your changes).</cmd><stepresult id="v5040536">The new group appears in the content tree.</stepresult></step></steps><result id="result_8E82944CCCEB461C96873A9B38F8E599">You have created a network element group.</result></taskbody></task>
04/11/2023
Reload
Surviving Thriving in an XML World
04/11/2023
Render
Surviving Thriving in an XML World
04/11/2023
References
DITA Users (dita-users) Yahoo! group
“Structured Information: Navigation, Access, and Control.” Steven J. DeRose, 1995http://sunsite.berkeley.edu/FindingAids/EAD/derose.html (retrieved 15 Sep 2013)
“Crash Course for Content Management.” Vasont Systems https://www.vasont.com/resources/resources-crash-course-for-content-management.html (retrieved 11 Nov 2013)
DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA. Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt. IBM Press, 2011.
Surviving Thriving in an XML World
04/11/2023
Questions?
Surviving Thriving in an XML World