How do you keep your content moving forward, while you are weighed down with baggage from the past? How do you change course when the tracks ahead seem to have washed away? Come hear the editors of the DITA 1.3 specification talk about creative strategies they put into place to streamline the process of developing a version of the specification, improve the quality and usability of the content, and get to their destination on schedule.

1. @robander @kriseberlein #LavaCon
Keeping the Content Train On the Tracks
(and on Topic)
• Robert D. Anderson, IBM
• Kristen James Eberlein, Eberlein Consulting LLC

2. Overview
• DITA 1.3: The project and participants
• Project boundaries
– What could (and couldn’t) change?
– Who sets the rules?
• Difficulties, expected and unexpected
• How did it go?
• Lessons learned

3. Learning objectives
• Based on our experience with a large,
complex, but collaborative document:
– Can one document serve many audiences?
– How to add new content quickly?
– How to encourage (more) participation from a
volunteer workforce?
– How do you keep the train going when an engine
runs out of coal?

4. This is a DITA presentation, but…
• … it’s not a <dita> presentation.
• It is about working with people, constraints
(both financial and time-based), technical
debt, and more.

5. About the speakers
 Robert Anderson
 Working on DITA at
IBM since 2001
 Co-editor of DITA
1.1, 1.2, 1.3 specs
 Lead for DITA Open
Toolkit
 Free time previously
spent on music,
books. Now, kids.
 Kris Eberlein
 Working with DITA
daily since 2004
 Co-editor of DITA
1.2 and 1.3 specs
 Chair, DITA TC
 Cats and quilts and
consulting! And
cars!

6. Checking your tickets …
• Expecting something more?
• Something different?
• Opportunity to step out before we leave the
station …
• Does anybody not know what DITA is?

7. Point of departure: DITA 1.2
• 1236 pages in PDF form, not all of it perfect
• Relied on by authors, vendors, industries
• Needs new features to keep up with demands

8. Starting up the engine
• Engineers: OASIS DITA technical
committee
– Vendors, companies using DITA,
individuals
– Mostly volunteers (not a full time job)
• Route restrictions:
– MUST be backwards compatible
– Backwards compatibility
– CANNOT BE backwards incompatible

9. See any obstacles on the track…?

10. The route …
• Backwards compatibility
• Multiple formats (PDF, XHTML, …)
• OASIS style
• Once done, at least six months to approval
• Point of departure: Address complexity

11. Expected delays

12. Everybody has their favorite gauge
• Contributors from different companies,
different backgrounds, with different goals
• DITA 1.2 process: contributors drop off raw
materials and (occasionally) a design plan
• Any guess how that went?

13. Our approach
• If you want a new stop for the train, YOU build
it. (After getting permits and plans approved.)
• Editorial job becomes connecting the tracks
• Result: 1.2 took 2 years to integrate new
content, 1.3 took a month

14. Complexity of existing track
• Known issue: many in community feel old
version is too complex or complicated
• But … new features needed in DITA 1.3
• How to add new features without making
things worse? Or even while making things
better?
• Seriously, that’s a question for the audience

15. Our approach
• Initial: New content goes with related content
• Later: Simplify both old and new, consolidate
old information that was poorly organized
• More later on the unexpected side of this
issue…

16. Lack of infrastructure
• Few existing tools,
no funding for tools
• But… we have to write, integrate, review
• How to manage collaborative writing
and reviewing, without common tools?

17. Our approach
• Use DITA, with our own authoring tools
• Free online tools: Trello
• Use DITAWeb provided by Mekon
• Use version control (SVN) provided by OASIS

18. DITAweb for reviewing
• Made it easy for people to
participate and see ALL comments
• Very successful:
– 543 comments (does not include
comments on comments)
– Participation by 94%
– 2-week review closed on time
– We had to tell people to stop
adding comments!

19. Complex information
• How to get feedback on everything, when
reviewers have only seconds to take it in?

20. Our (eventual) approach
• Break it up into small packages
• Who knows what these pictures came from?
• Also, spent more time on cleanup than new
work

21. Track built with volunteer labor
“Every emergency was met by calling for volunteers, and …
the volunteers were always forthcoming. Unfortunately
volunteering was relied on not only for emergencies, but for a
good deal of everyday work that should have been organized
as routine; and the inevitable result was that the willing
horses were overworked. … Men were allowed to do too
much, and they were told afterwards that they had done too
much; and that is not discipline.”
-- Apsley Cherry-Garrard,
The Worst Journey In the World,
published 1922

22. Our approach
• Prizes! Gamification!
• Badger contributors and reviewers
• Bite-sized reviews
• Next time:
– Limit how much any one volunteer can
take on
– Spread the work around

23. Bullet train versus scenic route
• One document, many audiences
– Technical implementers and end users
– Some want “Just the facts”, some want examples
– Some only want the basics (core DITA architecture
and elements), others want it all
• Is this possible?

24. Our approach
• Remember current audience – focus on what
currently exists, rather than what “should be”
• Everything correct, but as readable as possible
– The most complex parts of a technical standard
will always be technical. But they can still be
described for a broad audience.
• Multiple editions

25. Three editions of DITA 1.3

26. Unexpected delays

27. Existing track
• First version (DITA 1.0) was well designed,
took you where needed
• DITA 1.1 added lines
• DITA 1.2 built new routes everywhere, didn’t
shift any existing routes
• DITA 1.3 started with same approach
• What should we have done?

28. Our (eventual) approach
• As much as possible, shift the existing tracks
to something that (today) makes more sense
• If doing it all over –
– Before adding anything new, look at what exists
– Understand what can change (and whether there
are resources/support for reworking content)
– Consider initial rework/clean up before adding
new content

29. “I can run this whole train myself!”
• When a document is (largely) produced by
consensus, how do you handle disagreements?
• What if somebody threatens to stand in front
of the train?
• Surely nobody has
encountered this … ?

30. Our approach
• Pause arguments to cool down
• Settle contentious issues with smaller groups
• Only two editors allowed to touch actual
content, with consistent approach
• Ultimately, TC chair issued a dictate

31. Engineer burnout
• When the going gets tough,
have a second engineer
– “But we can’t change X
because of Y and if we
change Y then Z has to be
fixed and if we do Z then we
have to BUILD A WHOLE
NEW SYSTEM TO KEEP
GOING!!!!”

32. How did it go?
• On track to release December 15-17, 2015
• Biggest successes:
– Learned lessons from DITA 1.2
– “Build it yourself” process for new content
– Small reviews
– Style guide / content cleanup
– Consolidate redundant content / remove
extraneous content
– Flexibility – willing to regroup frequently

33. Lessons for next time
• Do not assume existing content is properly
organized, or even worth keeping
• Try not to hold so tightly to “backwards
compatibility” (subject to customer approval)
• Have more engineers, maybe a paid one
• Develop a more cohesive, long-term strategy

34. What else should we have done?
• Ideas from the audience?