Tech Writer Tips & Tricks: Advanced DITA

Tech Writer Today’s Technical Writing Tips and Tricks column is brought to you by Adobe Systems, Inc. Download a 30-day free trial of Adobe FrameMaker here.

You’ve started writing DITA topics and maps, you have your technical communication processes in place, and your publishables looking darn good. But are you wielding the full power of DITA?

• Conrefs: For those of you who shy away from text insets, rest easy with content references (conrefs). They let you use content from one source in many places, with none of the hassles that text insets cause. You can really maximize your re-use using a basic set of conrefs. For example: standard warnings or notes, UI task steps, explanations needed in many places. Write once, use many times. Not only does it save the authors times when writing, it makes changing things a breeze, ensures consistency, helps control standards and approvals issues, and saves HUGE money upon translation.
• Attributes/conditional content: The key to single sourcing is the ability to show only the content you want for a deliverable. DITA lets you set attributes that identify audience, product, platform (the three main attributes, but there are others) on almost every element. This means that one topic could be written for multiple end-deliverables. From doing simple things like hiding graphics for online help to more complex solutions like writing one set of topics for both Mac and Windows users (but they never know that), you can maximize your single sourcing and keep your topics nice and streamlined.
• Training content: DITA 1.2 introduced a way to integrate documentation with training content. The “super topics” in the learning and training specialization allow you to pull together existing tasks, concepts, and references to create coherent training modules, complete with summaries, goals, and assessments (quizzes!). Now you can single source across departments, saving even more time and money. This is going to be the next big thing in the DITA-verse.
• Keyrefs: There are a bunch of ways to use keyrefs (also new in DITA 1.2), from adding another layer of maneuvrability to conrefs to controlling when links display. I think of it as flavoring. I give a conref or an xref a flavor when I create it, then invoke that flavor in the map for publishing. As with most things DITA, it takes some upfront planning and someone to ensure the whole team doesn’t go “flavor” crazy, but it makes controlling conditional content a lot easier than attributes.
• Glossary: If you haven’t started using the glossary topic type yet, take some time to investigate it. This can not only give you a coherent (and product- and user-specific) glossary for your deliverables but can also be converted into tooltips or pop-up descriptions.
• Bookmaps: If you’ve used nothing but plain DITAmaps, you may not even know what you’re missing with Bookmaps. They help create frontmatter and backmatter, and help identify parts and chapters as well. Although not magical, they have different support in the DITA-OT. They could be the solution you need for something odd like creating a double index for Japanese deliverables.
• Best practices: If your tech writers are writing concepts that are actually procedures or tables in their tasks, they’re probably not following DITA best practices. It may be time to brush up on DITA best practices to remind everyone how to ensure their DITA writing is consistent and meets users’ needs. Hire your local (or international) expert in DITA training and make sure everyone on your technical communication (and training) team attends.