surviving in an xml world

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


04/11/2023

What is DITA XML?

Darwin Information Type Architecture

eXtensible Markup Language (widely used)

One implementation of Structured General Markup Language (SGML)


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


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


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


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


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


04/11/2023

Steve’s Development Process


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


04/11/2023Surviving Thriving in an XML World

04/11/2023

Pace


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)


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


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!


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)


04/11/2023

Extract: Book Map


04/11/2023

Extract: Navigator


04/11/2023

Extract: Local Folders


04/11/2023

Edit: Normal View


04/11/2023

Edit: Tags On View


04/11/2023

Edit: Text View


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


04/11/2023

Render


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.


http://sunsite.berkeley.edu/FindingAids/EAD/derose.html

http://sunsite.berkeley.edu/FindingAids/EAD/derose.html

https://www.vasont.com/resources/resources-crash-course-for-content-management.html

https://www.vasont.com/resources/resources-crash-course-for-content-management.html

04/11/2023

Questions?


surviving in an xml world

Technology