Structured authoring | 10 questions to ease the transition

If your technical writing team is considering a move to structure authoring, you'll probably want to answer some fundamental questions before investing in tools or a specific workflow. Here are some issues to consider as you plan for such a move.

• Is a single requirement pushing you toward structured authoring, or are there multiple reasons such a move would be beneficial?
• If it is a single requirement, are there other options that would help you meet that goal and be less labor / cost intensive? For example, do your existing tools offer features for content re-use that you haven't explored?
• Is the amount of labor you will save by moving to structured authoring going to be greater than the learning curve, tool costs, and long-term changes in workflow?
• How will you track content that is re-used? Do you have a tool to manage these blocks of content, or do you need to come up with a metadata scheme and a search process for finding that content at a later time?
• Do you need to shoe-horn your existing content into strict topic types (DITA tasks, concepts, etc.), or would it be more cost effective to start with a generic topic type until you have more time to tear apart your existing content and make it more granular?
• Is your content complex enough to warrant a move to standards such as DITA and DocBook, or would it be simpler to create a less-complicated XML / XSLT workflow?
• Is your team prepared for the technical challenges of working "under the hood" with tools like the DITA Open Toolkit, or do you need a WYSIWYG-type editor that offers built-in support for structured authoring?
• If you choose a tool with structured authoring support, does that tool produce the output formats you need (PDF, WebHelp, etc.), or will you need to do a lot of customization?
• Is your existing documentation filled with custom formatting and functionality that will make a conversion to XML difficult? If so, can you eliminate some of these features for the sake of future portability and a simpler conversion?
• What tasks can members of your team begin working on now, in preparation for the conversion? Testing whether trial versions of tools can import your existing documentation projects? Cleaning up content that isn't likely to convert well?

Moving to structured authoring can be costly and labor-intensive. However, asking the right questions first can make the transition much easier for you and your coworkers, and save you money.

Related: Which XML editor should I use?.

10 reasons to stop printing manuals

Is your company still producing printed manuals? If so, there are many reasons to consider converting these documents to an electronic format. For example, portable devices such as tablet PCs and smart phones have made it possible for technicians to access electronic how-to guides in the field.

Here are a ten reasons technical writers should consider eliminating paper manuals.

No printing costs: Ok, this is a no-brainer. However, it is also the most likely to improve your department's budget. Also, you can save a lot of trees and help your company become more environmentally friendly.

Rapid distribution: A PDF can be emailed instantly to anyone, and so can links to documents stored on a server. Also, technologies such as RSS can be used to immediately alert users of updates.

Easier and cheaper updates: There's no need to reprint the guide if you need to correct mistakes or make changes. Just update the electronic version and publish it to a server.

Consolidation of end-user information libraries: All of your technical documents, as well as other information resources, can be accessed by end users from a single portable device.

Elimination of archive space: Department archives can be moved from storage vaults to servers or fixed media, saving both floor space and money.

On-the-fly translation: End users can use software to translate electronic documents into various languages; this is not possible for printed manuals.

Better navigation: Try implementing a full-text search on your printed manual. (If you figure out how, let me know.)

Improved accessibility: Screen readers and other accessibility tools only work on electronic documents. To a blind person, your printed manual is useless.

Improved sharing and cross-referencing: End users can easily link to electronic documents, even specific sections, from their internal processes and procedures.

Crowd-sourcing and collaboration: If a user spots inaccurate information in a printed manual, you'll likely never find out about it. However, online formats such as wikis allow users to suggest changes easily and contribute new content based on their best practices.

Of course, there will always be cases where printed instructions are best. For example, instructions for setting up residential Internet service would be useless on a server; the user would not be able to access those instructions. Think carefully about the needs of your users and choose the best format.

Related post: Writing user manuals | Tips and templates.