Have you thought about extending your DITA implementation beyond the technical communications team? Would it be helpful for those support team members who document troubleshooting content? Believe it or not, there are many cases where a non-technical writer might want to leverage the power of DITA. They may be contributing as subject matter expert (SME) authors or reviewers, or they may be integrating code (like APIs) with documentation. It may be challenging to convince them to jump in, but when the water’s fine, and your tools are configured properly, even non-technical writers can learn to swim.
With very few exceptions, these non-writers are busy people and don’t have the time or interest in learning the basics of DITA. They want writing or reviewing to be quick, easy, and as similar to their old tools as they can get. One of the great benefits of DITA is that it is flexible and the methods by which you access or create content depend only on your ingenuity (and sometimes budget).
Reviewers
There’s nothing magical about reviewing DITA content. You could create a PDF and send it in an email to reviewers and still get comments back but that’s an inefficient way of working with information. What you’re aiming for is concurrent, dynamic reviews, where multiple reviewers can see each other’s comments, where only one copy of a reviewed piece of content exists (rather than a copy in everyone’s hard drives via email, then copies of those copies emailed back to the author), and where authors need only accept or reject the changes to finalize the XML source.
These may seem like small improvements over the email-an-attachment method, but they really help keep reviews under control (see http://ditametrics101.com/ for ways to put hard numbers around your potential or actual savings).
Many high-end CCMSs provide an easy-to-use web-based interface that enable concurrent reviews. They usually also throw in some sort of project management aspect so authors can assign and enforce review dates.
You can also build your own workflow using a document management repository, like SharePoint, that gives you the collaborative and workflow aspects, but lacks the direct connection to your XML source. This adds an extra step for your authors who have to open both the reviewed document and the XML source to make the changes.
Contributing Authors
There’s no reason a SME author cannot contribute content in DITA. However, considering their limited time and interest in learning documentation best practices (and DITA best practices to boot), you need to overcome a couple of hurdles to do this well:
- Provide an easy authoring interface
- Guide them in best practices without hindering them
- Confirm the markup and edit
Provide an Easy Authoring Interface
These contributing authors need to have something that’s as easy as Word to author in. A variety of options exist, including using oXygen’s forms-based authoring, using a simplified XML editor like Codex, or using Stilo’s new on-the-fly conversion interface AuthorBridge, which doesn’t require authors to have any knowledge at all of DITA or even elements. Some CCMSs, like Paligo, even provide a simplified interface for authoring (often, this is a paid add-on).
No matter which options you consider, remember that it’s important that authors see content that is as close to published output as possible. Everyone is used to WYSIWYG authoring (a Word document saved to PDF looks exactly like what was in Word) but DITA can include all sorts of formatting on publish that may be invisible to authors. As an example, all content marked up as a <note> element may have the word “Note:” automatically inserted on publish. If the author doesn’t see this, they’ll likely add their own word before continuing on with the content of the note itself, which then turns into a redundant effort that needs to be fixed.
Where possible, customize the look of the authoring interface to match the output.
Guide Contributors in Best Practices
SME contributors have not spent years perfecting their writing techniques or pondering the benefits and drawbacks of minimalism and topic-based writing, so if you want them to create quality content that doesn’t break all of DITA’s best practices, you need to guide them (without hindering them).
Usually, you’re going to spend some time determining exactly what these authors need to write, and then create templates or forms that help guide them through their very specific creation process. Even better, you also ensure consistency this way. Think of all the possible ways troubleshooting information can be written. Now imagine that you get to design the form that Support personnel fill out that guides them through the consistent creation of a DITA topic.
For a tool like Stilo’s AuthorBridge, this means that you’ll need to ensure that they understand the scope of a topic and when to use the appropriate topic type. You can guide them with sample guidelines and explanations right in the templates you provide to them.
Confirm the Markup and Edit
As when anyone who doesn’t know DITA is trying to markup content (or where the markup is invisible to them, as in forms and AuthorBridge), you’re going to want someone who knows DITA to review the elements used and make changes when necessary. I like to perform the language edit in coordination with the markup edit because it makes little sense to appropriately markup poorly written content (for example, a SME has written a procedure in paragraph form).
Integrating DITA with Code
Because DITA is XML and code is either XML or can be converted to XML, there are all sorts of opportunities to get programmers to describe syntax in the code and output the syntax and syntax descriptions as DITA content. It takes some effort on the programmers’ end (they must actually document the descriptions somewhere, even if it’s the code). And you will need custom programming to get everything working together, but it’s absolutely possible to create, for example, an automated nightly build of the code that creates HTML and/or PDF output of the API documentation.
Conclusion
DITA for non-technical writers is very much a real option, with some planning and tweaking of tools and workflows. Whether it’s embedded into programmer’s code or is through a simplified authoring interface, getting SMEs to create DITA content is an excellent, time-saving tactic.
