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.

Keeping the Content Train on the Tracks (And on Topic)


Published on

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.

  • Be the first to comment

  • Be the first to like this

Keeping the Content Train on the Tracks (And on Topic)

  1. 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. 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. 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. 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. 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. 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. 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. 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. 9. See any obstacles on the track…?
  10. 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. 11. Expected delays
  12. 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. 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. 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. 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. 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. 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. 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. 19. Complex information • How to get feedback on everything, when reviewers have only seconds to take it in?
  20. 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. 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. 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. 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. 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. 25. Three editions of DITA 1.3
  26. 26. Unexpected delays
  27. 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. 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. 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. 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. 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. 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. 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. 34. What else should we have done? • Ideas from the audience?