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.
Darwin Information Typing Architecture (DITA) is a sweeping revolution in technical writing and training. DITA introduces a different way of writing; a way that satisfies the ways users look for information and is therefore more usable. Additionally, authors work more efficiently by being able to easily single source and re-use content. The overall user experience is more consistent because format is completely separated from content (format is handled on publish only, not by the authors). Consider carefully, and if you choose to make the switch to DITA, it’s already time to start planning.
And it’s no simple task. It’s easy to become overwhelmed by the forest and lose sight of the trees. DITA implementation is a big undertaking, but doable if you stay focused on some salient points:
- Understand the basics first. If you don’t understand the topic types (task, concept, reference) and why to use them or don’t understand why each topic should be in its own file, take a basic course and arm yourself with knowledge first.
- Get an XML editing tool. Take your time picking picking out and try them out first. Don’t limit yourself to just one. Not all XML editors are made equal; they each have their strengths and weaknesses. But remember that DITA content means you can use whatever authoring tool you want and switch back and forth without headaches. It often helps to have more than one XML editor available (even if it’s just one license). For example, Adobe FrameMaker has awesome potential, especially when combined with Leximation’s DITA-FMx tool, but sometimes nothing can beat the at-your-fingertips usability and troubleshooting abilities of oXygen. And XMetaLcan be customized up to the hilt. There are another half dozen XML editors that are either free or are meant for a specific audience (users with SharePoint, users who do not know or want to know XML tagging, etc.). They all have their place in my arsenal of XML editors and I pull each of them out as needed.
- Have an idea of your end-to-end solution.When deciding to move to a DITA authoring environment, make sure you have some idea of your entire process, from authoring to publishing:
- How/where you will store (and have your authors access) topics, maps, and graphics. CMS? Sharepoint? A version control system? File server? They each have their drawbacks, but make sure you know what they are before you commit your documentation team to using one of them. A smart team maintains a single source for content, even through decades of releases. This is where putting money in for a good solution in the beginning can save you millions down the road.
- Content re-use and single sourcing: How are you going to make this easy for authors? Who’s going to do the architecture work that’s necessary to make re-use decisions and enforce processes? What tools can you make use of?
- Translation: If you need translation, what processes will be involved, how much can you automate, what extra tools do you need, how will you manage source changes once content has gone for translation?
- Publishing: This is the big one. There are at least a dozen publishing solutions in the DITA world, and it’s a rapidly growing field. DITA-OT with customizations? A third-party tool like WebWorks? Through your XML editor with a plug-in? Directly from a CMS? Which one will you choose? This decision is going to influence allthe other decisions you make, from tools to access, so it’s the whammy you have to whack early on.
- Stay on top of the DITA news. The DITA version (currently 1.2) is not tied to the DITA Open Toolkit (DITA-OT) version (currently 1.5.3 but soon to be 1.5.4). The DITA-OT is a set of XML transforms that lets you publish default and customized end products (PDF, online help, etc.) as opposed to the DITA version, which is the set of elements and topics that you can use. Your tools will use a specific version of both DITA and the DITA-OT, but you can upgrade the DITA-OT independently of all other upgrades (DITA version and XML editor version). For a tech writer using the DITA-OT to publish, those DITA-OT upgrades can be gold (and save you from expending effort developing a workaround they’ve just fixed).
- Get some expert help. Consultants can give you the vital inside information, based on years of experience with organizations like yours, to get you headed in the right direction from the start. A few quick discussions can save you months of work, so if you can get the budget for it (anywhere from $500 to $50,000+, depending on the amount of involvement you want them to have), go ahead and hire the people who have done it all before. They give you customized feedback on the solution that will work best for your needs.
- Make sure your team gets the training they need. Transitioning to topic-based writing with all the associated tools and processes can be a difficult time, but getting the entire team trained by the same trainer at the same time can boost everyone’s confidence in the project.
While a transition to DITA can seem overwhelming, it’s well worth the effort. From better, more consistent documentation to efficient use of content and author time, the benefits far outweigh the drawbacks.
A special thank you to Adobe Systems, Inc. for sponsoring our Tips & Tricks column. You can learn more about Adobe’s industry-leading technical communication tools by going to their website.
