Geeks With Blogs

Technical Writing by Mark Metcalfe, Publications Professional

Topic-based information is the way to convey information because answers to issues need to be concise, portable, and relevant. The trouble is that many companies have a lot of information already stored in old documentation formats. User guides are becoming rare; and they should, because the effort and cost involved in creating a user guide is too great compared to the number of users who need comprehensive information. Quick Start guides are replacing user guides and the comprehensive information is being moved into smaller chunks of information.

It is an easier job to create a DITA-based, XML-powered topical information system from scratch than it is to retrofit existing documentation into a new model. However, if your company is contemplating such a move, there are several phases you need to consider before making the switch.

Phase 1: Make sure your content is well-typed, meaning that the manuals are updated to have a consistent, standardized organization. Make sure that your sections can standalone as discrete topics, and can be typed as concept, task, or reference, (or some derivative of these types). Doing this will improve the usefulness of the documentation, even if you never convert the document into XML.

Phase 2: Choose the XML solution that works best for your situation and roll out the changes. Remember that customers do not care about the source of the information; they only care about the output, so a company should consider the costs of conversion, the longevity of the tools you will use (will the solution grow with you?), and the ease of use so that people outside of technical publications can contribute content in some way.

If Phase 1 is done properly, and the documentation is laid out consistently, automation can convert much of the content. If it must be done manually, a well-formed document will take much less time to convert, so spending time on Phase 1 is very important.

After the content is properly tagged, then it becomes a matter of how the content is distributed and displayed, which can take several forms (for example, HTML help, PDF, mobile help). This should be determined and developed while writers are engaged in Phase 1 activity.

Mark Metcalfe

Posted on Monday, July 6, 2009 9:09 AM | Back to top

Comments on this post: Converting Legacy Info to Topics

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © TechnicalWriting | Powered by: