DocTrain West 2009: Mark Lewis on “DITA Metrics: Cost Metrics”

Mark Lewis‘s session presented metrics with which you can show ROI for DITA by reusing identical and similar topics. See Lewis’ White Paper here on the Content Wrangler for details.

An engaged discussion ensued which shows the interest in tangible metrics:

• There was no immediate answer about the total cost of ownership for converting to and maintaining DITA. But the burden of proof in terms of TCO shouldn’t rest with the documentation team – which most likely doesn’t have all the numbers for it, anyway. Instead, the team can try to figure what management is willing to spend money for and try to tap into that.
• If you have a diverse team where some writers are faster than others, you can either use a mean topic development time (instead of the average; see the comment wall of the DITA Metrics group in the Content Wrangler ning network). Or you can use normalized sizes and assign each writer a factor to define how long he needs to complete one of those development sizes.

DocTrain West 2009: Richard Hamilton on “Managing the Move to Structured Content”

Richard Hamilton ran a session to talk about managing the move to structured content. Richard is a really pragmatic guy, so he talked about the why, what and how of managing the transition.

He started with several reasons of why and when not to transition:

• When there’s neither a benefit for the bottom line nor for the customers/users
• When it leaves you without a productive and operable documentation environment at any stage
• When you cannot commit to the new process (i.e., you’re afraid to burn your bridges behind you)
• When you cannot train or run a pilot project

To select what to carry over, he advocated converting only the used, required contents – and when in doubt to leave it out. He also said to carry over all the existing semantics, but not to add any new semantics, unless they add a proven value at reasonable cost: Don’t let the perfectionists run wild and build a more perfect solution – it’s difficult enough as it is.

For the “how”, he suggested to get outside help, esp. with the actual conversion – though that may require to clean up legacy content to get it ready for sensible conversion.

DocTrain West 2009: Ann Rockley’s keynote “Moving to Structured Content”

Ann Rockley gave her keynote address about how to move to structured content.

She focused on the project stages in implementing structured content. To get wary or hesitant writers on board, it’s essential to teach them, so they understand how the way they work will change: First, teach the concepts as well as the benefits which are consistency, reusability, guidance in writing and enhanced productivity when you don’t have to worry about stuff like structure and formatting. Then teach the modeling of content, then the guidelines for writers to adhere to. (The address did not discuss the business case and change management – for time reasons, I guess.)

She emphasized that structured writing should be taught separately from the tool, lest writers will focus on the tool rather than concepts and process. Then get a tool which matches the writers’ skills.

DocTrain West 2009: Joe Gollner’s keynote “Knowledge Archaeology: Raiders of the Lost Art”

To open DocTrain West, Joe Gollner delivered an insightful and concise opening keynote address about converting unstructured legacy documentation to structured content.

First, he reviewed types of content: “Opaque” content, such as paper copies, is not processable. “Annoying” content insists on unwieldy proprietary formats. “Polluted” content is corrupted or mixes formats. And “tolerable” content comes along as HTML, a Word document or something that is more or less manageable.

For these types of content, there are various strategies to convert it: You can do it manually, get a tool to do it, or outsource it. His best practice in a nutshell is to stay flexible and open to find the best possible mix of tools, specialist help and automation.

Spelled out as a process, it looks something like this:

1. Decide on the legacy sources and the target schema to convert.
2. Analyze your sources carefully (and possibly clean them up where necessary).
3. Map sources to the target schema.
4. Establish conversion rules (and the gaps to fill by manual editing).
5. Perform the actual conversion.
6. If possible and desired, add necessary and useful metadata, links and connections to topics.
7. Check the converted contents for accuracy, consistency and completeness (according to initial scope).

He also pointed out a few caveats:

• Do not to underestimate the complexity of the conversion process.
• Focus on the conversion purpose and business case, because neither structured content nor conversion can be an end in itself.

DocTrain West 2009: Linda Urban’s workshop “Topic-Based Authoring: Getting Your Feet Wet”

On March 17, I attended this full-day (7 hours) pre-conference workshop on topic-based authoring (TBA). Linda Urban has been working with topics for about 20 years now. Add her experience in teaching technical writing, and I can imagine few people better qualified to present this topic.

It’s an excellent, well-structured workshop which

• Provides an overview of TBA, its concepts and its principles
• Shows what TBA is, what it’s not, and why it’s useful
• Defines topics and their elements, as well as information types
• Discussed how to write effective topics
• Demonstrates best practices to introduce TBA and pitfalls when converting legacy contents
• Includes many practical exercises, such as identifying, chunking, and connecting topics into coherent documentation

I took away several insights that came from Linda’s practical experience or from the discussions, e.g.,

• Improve usability when converting legacy contents, don’t convert stuff that nobody uses.
• When in doubt what to cover in topics, start by documenting the users’ “happy path”.
• Connecting beats chunking: Completeness and usability of TBA become apparent when you connect your topics.
• While TBA affords faster reviews, don’t forget to review (or eliminate) older topics.

Several participants actually knew about TBA already: Some had come for a reality check and some because they need to teach TBA to their team. And it seemed everybody got a lot out of it! I think this is a great 101 course workshop since it’s tool-agnostic and focused on the principles and processes.

I understand that this was not an “exclusive engagement”, so if you missed it or need an on-site workshop, contact Linda. (I get nothing for this endorsement, I just think it’s a really good course… 🙂 )