Resources

Help us, Obi Wan Kenobi; you’re our only hope … for a fantastic DITA implementation!

By Jacquie Samuels – Darwin Information Typing Architecture (DITA) is experiencing a gratifying upswing of adoption over the last 10 years or so. But adopters are often adrift when it comes to how, exactly, they should use it.  

The problem
DITA is an XML infrastructure, not a set of tools or a writing standard or a combination of both. Although the topic types seem to guide you through the ideal authoring model with their set of allowed elements, when you really start implementing DITA, you realize that authors have a great deal of flexibility when shaping their content into DITA topics.

That flexibility is awesome, like a Jedi padawan experiencing the power of the Force for the first time; however, the lack of guidance can lead many a team not just down an unfortunate path, but to actually fail at DITA adoption (and let’s face it, that will only lead the Dark Side—writing in Word).

Here are some specific problems that authors face when adopting DITA:

• What kind of content should go in a reference topic versus a concept topic?
  • How do the authors and the users distinguish between them?
  • What’s the standard they are writing to?
• Should you customize and specialize the DITA topics to meet our specific content needs? If so, what’s the best way of doing it?
• You’re updating the writing infrastructure; in doing so, what processes can you improve or replace?
  • How can the best result be achieved?
  • How can you more tightly integrate writing processes with development to align with product changes?
• Tools: From content storage and maintenance to publishing, there’s an entire life-cycle for content as it goes from planning to publishing (and post-publishing).
  • DITA includes none of these tools. Not one.
  • At the time of publishing this article, there is no one tool that can do it all.
  • The best you can do is assemble your tool lineup to meet your specific requirements, sometimes a daunting task.

It’s not good enough to simply follow another company’s DITA implementation choices—because what’s best for them is not necessarily what’s best for you. There are a thousand choices to make and you want to make sure each one helps take you one more step down your DITA Jedi path.

The solution
Every padawan needs a Jedi Master. You don’t need to learn DITA all on your own—you can have your own Obi-Wan Kenobi.

Tool vendors, although always willing to help, are not a particularly good source of objective advice. First of all, their view of the entire DITA adoption is skewed to their particular part of it. Secondly, vendors often have a vested interest in pushing you towards a particular path (although not usually for nefarious reasons). The best tool vendors admit partiality and partner you up with a DITA consultant instead.

Consultants guide you through the entire process of DITA adoption, including but not limited to:

• requirements gathering and analysis to understand where you are and where you want to go
• legacy content review to identify both problems and possibilities
• writing standards, templates, and training to guide authors in content creation
• authoring and feedback so authors get help and guidance as they work through the known authoring ways while also meeting corporate goals
• process analysis and enhancement to cut down on internal costs of content creation and publishing
• tools to enable your goals and processes
• publishing and usability to ensure the users’ experience is nothing less than glorious, and
• metrics to track your success and identify areas for continuous improvement.

Shameless plug
Here’s the shameless plug.

I’ve been working with Precision Content for the last year or so and I’ve never seen any other consultant take the DITA topics and create an entire writing standard around them the way Precision Content has. Each topic becomes not only easier to write, but very specifically focussed on a goal so that users can gain the ultimate benefit—the clearest, most easy-to-understand documentation. The content doesn’t just become XML after adoption—it is completely transformed into highly usable content, appropriately typed, clearly written, and completely standardized across the board.

Precision Content has an integrated approach that leverages DITA as the infrastructure, but then takes it far beyond what anyone else has done with it. It’s like comparing Yoda to…well…all the other Jedi Knights.

DITA is not a writing standard and provides so very little guidance on the matter. Other DITA consultants follow the basic best practices; however, there’s a massive gap in what authors need to have to create great, consistent content and what DITA offers. Precision Content bridges that gap with a fully integrated writing standard ready to be leveraged and even adapted to the client’s specific content requirements. And all of it, every single piece of their writing standard, is based on knowing how people use documentation and making it as user-friendly as possible.

Precision Content is what DITA was meant to be.

About Jacquie Samuels

Jacquie Samuels is the owner of Writing Wise; a technical communications and DITA consultancy based in Ottawa, Canada. Jacquie has been working with DITA since 2005 and partners with Precision Content Authoring Solutions on large content transformation and information architecture projects.

Follow Jacquie Samuels on Twitter

Graphic citation: Photographer, eRachel11. (2010, July). Help me Obi Wan Kenobi, you’re my only hope… [digital image]. Retrieved from www.flickr.com

456 × 456

Tweet