Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Surviving in an XML World

634 views

Published on

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.

Published in: Technology, News & Politics
  • Be the first to comment

Surviving in an XML World

  1. 1. Surviving Thriving in an XML World Steven Jong and Anna Pratt
  2. 2. Overview 1. 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 10/15/2015Surviving Thriving in an XML World
  3. 3. 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 10/15/2015Surviving Thriving in an XML World
  4. 4. What is DITA XML? Darwin Information Type Architecture eXtensible Markup Language (widely used) One implementation of Structured General Markup Language (SGML) 10/15/2015Surviving Thriving in an XML World
  5. 5. DITA Advantages Implements 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 10/15/2015Surviving Thriving in an XML World
  6. 6. DITA Disadvantages Rigidly 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 10/15/2015Surviving Thriving in an XML World
  7. 7. To quote a wise man: “Here’s my number. My company can help you when you’re ready to convert back…”
  8. 8. 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
  9. 9. 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
  10. 10. Work Flows Hierarchies Checking files in and out Opening 5 to 7 pieces of software
  11. 11. Favorite? Mistakes Forgot to add topics to source control Referenced a deleted topic Worked with transforms (or not)
  12. 12. 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 10/15/2015Surviving Thriving in an XML World
  13. 13. 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 10/15/2015Surviving Thriving in an XML World
  14. 14. 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 10/15/2015Surviving Thriving in an XML World
  15. 15. Steve’s Development Process 10/15/2015Surviving Thriving in an XML World
  16. 16. Survey Says… About the transition…
  17. 17. 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
  18. 18. Pain Points Transition 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
  19. 19. Working From a Distance 10/15/2015Surviving Thriving in an XML World
  20. 20. 10/15/2015Surviving Thriving in an XML World
  21. 21. Pace 10/15/2015Surviving Thriving in an XML World
  22. 22. 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) 10/15/2015Surviving Thriving in an XML World
  23. 23. 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 10/15/2015Surviving 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
  24. 24. Surviving Let it go… Ownership Format control Page 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!)
  25. 25. 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.”
  26. 26. 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:
  27. 27. Thrive on… Discover the joy of reading log files and code NEVER lose your sense of humor! 10/15/2015Surviving Thriving in an XML World
  28. 28. 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) 10/15/2015Surviving Thriving in an XML World
  29. 29. Extract: Book Map 10/15/2015Surviving Thriving in an XML World
  30. 30. Extract: Navigator 10/15/2015Surviving Thriving in an XML World
  31. 31. Extract: Local Folders 10/15/2015Surviving Thriving in an XML World
  32. 32. Edit: Normal View 10/15/2015Surviving Thriving in an XML World
  33. 33. Edit: Tags On View 10/15/2015Surviving Thriving in an XML World
  34. 34. Edit: Text View 10/15/2015Surviving Thriving in an XML World
  35. 35. 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>
  36. 36. Reload 10/15/2015Surviving Thriving in an XML World
  37. 37. Render 10/15/2015Surviving Thriving in an XML World
  38. 38. References DITA Users (dita-users) Yahoo! group “Structured Information: Navigation, Access, and Control.” Steven J. DeRose, 1995 http://sunsite.berkeley.edu/FindingAids/EAD/derose.h tml (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. 10/15/2015Surviving Thriving in an XML World
  39. 39. Questions? 10/15/2015Surviving Thriving in an XML World

×