Managing Complexity: Making Effective Use of Sample DITA Documentation Sets

In early May every year, Atlantic herring by the thousands migrate from deep waters to dozens of local streams with herring runs. For a week or so, all the herring congregate at the base of the fish ladders before the pioneers begin to jump over the ladder gates to make their way upstream to spawning grounds. The successful fish attempt one ladder gate at a time and pace themselves. Ones jumping before or beyond the ladder gate become injured or exhausted.

By analogy, teams migrating to and investing in DITA face a series of decisions, each a ladder gate of sorts.
– Should we standardize on the informal or formal task topic type?
– Should we eliminate in-topic blocks in favor of reltable linking?
– Should we put all reusable content in content libraries or is it OK to continue to conref between topics?
– Should we migrate from conrefs to conkeyrefs?
– Should we constrain attribute values using subjectScheme maps?
– Should we integrate LwDITA Markdown topics with my XML maps?

Teams that jump to new DITA features without assessing costs and understanding benefits are candidates for injury or exhaustion. Realistically, how do teams unfamiliar with some of these DITA features get a feel for risks, long-term maintenance overhead, usability, and implementation costs? The DITA spec is mostly silent on these matters. Isolated code examples in specs and whitepapers offer insufficient context. It’s easy to implement 10-20 content libraries, but what would the impact be to an organization if it needed to scale up to 500-600 libraries? 1000 reltables? If we, as a DITA community, had a cheat sheet that calculated the relative cost and complexity of DITA features such as reltables or keys or subjectScheme maps, we’d be in good shape. Making tradeoffs and plotting a reasonable migration would be relatively straight-forward. Unfortunately, such a shared assessment does not exist. Networking with other DITA people who have implemented complex DITA features can certainly help, but in the end that still amounts to hearsay. To feel confident that jumping to a new, complex feature in DITA would actually benefit a team, it needs hands-on experience testing that feature in the context of a complete DITA documentation set.

In my presentation I make the case that teams wanting to get some hands-on experience with complex DITA features should become familiar with the sample DITA documentation sets available for download. The OASIS DITA Adoption Technical Committee has begun cataloging them (https://wiki.oasis-open.org/dita-adoption/ditaSourceSets) and I have been developing an ambitious sample doc set on my own (https://github.com/StanDoherty/project-alcuin). I will address the following topics:
1. How do teams obtain and use these sample DITA docs sets?
2. Which DITA features are implemented in each of these sample doc sets?
3. How can teams then use these sample doc sets to assess the relative costs/benefits of a feature?
4. How can interested teams contribute toward the development of future sample doc sets?

This presentation addresses a gap in our current DITA portfolio — the lack of ready-to-download DITA documentation sets indexed by DITA feature.

What can the audience expect to learn?

In my presentation I make the case that teams wanting to get some hands-on experience with complex DITA features should become familiar with the sample DITA documentation sets available for download. The OASIS DITA Adoption Technical Committee has begun cataloging them (https://wiki.oasis-open.org/dita-adoption/ditaSourceSets) and I have been developing an ambitious sample doc set on my own (https://github.com/StanDoherty/project-alcuin). I will address the following topics:
1. How do teams obtain and use these sample DITA docs sets?
2. Which DITA features are implemented in each of these sample doc sets?
3. How can teams then use these sample doc sets to assess the relative costs/benefits of a feature?
4. How can interested teams contribute toward the development of future sample doc sets?

This presentation addresses a gap in our current DITA portfolio — the lack of ready-to-download DITA documentation sets indexed by DITA feature.

Meet the presenter

Stan Doherty lives in the the Boston area and works as a manager and information architect at Oracle Corporation.

He serves as a founding member of the OASIS DITA Technical Committee, secretary for the OASIS DITA Adoption Technical Committee, and co-coordinator of the recently rebooted Boston DITA Users Group. Feel free to contact Stan if you are considering DITA, DITA tools, and DITA-aware CCMSs.

Contact: Stan@ModularWriting.com

⇐Return to Agenda