WritersUA: DITA pilot techniques
Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.
He recommends selecting your pilot project based on the following items:
- Right timeframe — don’t choose the project that has an imminent release
- Choose a manageable documentation set size
- Reduce risk by avoiding the strongest (or most critical) product
- Identify a product with a known need to improve the user experience
They had one person out of a group of twelve, a “senior in name only” writer, leave because of this transition.
The ideal team for a pilot will need cross-functional and complementary skills:
- Project management skills
- Tools and technology strengths
- Product knowledge and understanding
- Architecture and design skills
- Editor for standards and styles
Some advice on planning your content. (And it’s worth noting here that these apply to good writing and topic-oriented content rather than to DITA tools.)
- No autopilot writing
- Don’t just migrate existing content; you’ll get trapped in old paradigms (this assumes that existing content does not fit the DITA topic paradigm)
- Perform use case analysis and task analysis
- Determine the critical scenarios to document
- Focus on tasks; backfill supporting information as needed
Some interesting discussion of “task support clusters,” which include conceptual overviews, related tasks, deep concept, and reference information. (Michael Hughes did a presentation on this earlier today, which I unfortunately was not able to attend.)
They set up a DITA War Room in a small conference room and met at least daily (1.5 to 2 hours per day. Yikes). They set weekly goals and used small tasks to build momentum.
There was also heavy use of an internal wiki to put up initial “straw man” design, then revise, comment, and discuss.
Layering deliverables
Implementation deliverables were split out into smaller tasks, such as:
- Creating topic files, links, and navigation
- Testing links from code and navigation
- Creating task and reference topics
- Validating help against the user interface
- Creating concept topics for principles, guidelines, and best practices (“deep concept”)
- Validating content in the expert community
For the third time, he points out that they are no longer documenting how to use a check box, so I guess I’ll mention it.
Choosing the DITA toolset
Task Modeler (free) for building and managing ditamaps, defining relationships between topics, and creating skeleton topics (stub files).
DITA-compliant editor to edit your topics.
Compiler (part of open source toolkit). Compiler? What are they compiling? HTML Help? Oh. He just referred to Ant as a compiler. Ohhhhhkay.
Proof of concept
They picked a subset of the pilot to do the proof of concept.
The presenter’s boss is quoted as saying, “There’s no such thing as bad weather, only insufficient clothing.” I’m guessing that she’s never been to Minnesota in winter.
The objectives for the proof of concept:
- Learn and evaluate tools
- Address technical obstacles
- Specify end-to-end requirements
They learned that deliverable formats matter because they must deliver several different formats.
Managing costs
Purchase toolsets only for pilot team.
After completing proof of concept (successfully!), invest in tools for the remaining writers.
Wiki
They used their wiki to capture conventions and guidelines.
Improving acceptance
They paid attention to the change management issues. He doesn’t mention it here, but I would assume that the combination of an acquisition by IBM plus the requirement to change the authoring environment could have caused significant angst. Their approach included presentations, wiki content, email discussions, and online training.
At the point of transition, DITA boot camp was offered.
They used collaborative walkthroughs, or reviews, to help standardize their content development. Interesting. This sounds as though it could be a) threatening and b) an unbelievable time sink. But just maybe it might also c) help improve the content.
Other lessons learned
Think more, write less. (Don’t document the obvious, don’t document common user interface convention, write only if you’re really adding value.)
Don’t squander your ignorance. (If something makes you stumble in the interface, that will probably also cause problems for your users, so capture it.)
The more structured your content, the easier the transition to DITA.
Documenting the obvious teaches readers to ignore your text, so don’t document the obvious.
The handouts are available here: http://www.writersua.com/ohc/suppmatl/
