For years, technical documentation has been developed using word processing or page layout tools, such as MS-Word, FrameMaker, Quark, and InDesign. The output is a book-length document, typically released as a PDF, designed to be read front to back. But PDFs have significant limitations, both to your customer as well as to your sales and marketing groups.

Typically, customers don’t first read the technical documentation cover to cover and then use the product. They rather refer to the documentation when they are looking for an answer to a problem they’ve encountered with your product or technology. More often than not, they’ll start by searching the web for an answer. With luck, the PDF appears among the first in the list of search returns. But that’s left up to the Google search algorithm, which is not something you can control.

Then the PDF must be opened for the content to be viewed. This requires opening a separate Acrobat Reader application or a browser plug-in, which can take time. You can optimize a PDF to reduce its file size. But if the document is very long, or it includes heavy use of artwork, it can be slow to open.

Then the user must repeat the search within the PDF. If the answer isn’t in that PDF, then the search process must be repeated. You can hope they find an answer quickly. Or you risk an unhappy customer.  And customer satisfaction affects future sales.

Then there is the static nature of PDFs. While considerable resources may have been required to develop the content, that content is not easily shared throughout the company. Worse, you lose significant valuable information regarding customer use and feedback. And that’s another hit to your sales and marketing groups.

So what’s the option? Use the tools that optimize documentation for the web. XML is the document markup language for the internet.  XML documentation output can be a web page, as well as a PDF. Documentation produced in XML has powerful capabilities, including:

• Faster access. Technical information is presented in smaller “chunks,” produced and displayed using native internet and web-based tools.  Not only is it more quickly accessed by the user, it’s also easily edited by authorized users.
• Automated formatting. Most markup languages use separate stylesheets to format the output, such as CSS and XSL-FO. These define the corporate tech pubs style guide. Once these files are created, formatting is automatically applied across all XML content files. Content development moves much more quickly and freely.
• Web analytics. It’s now possible to learn how your customers use the content you provide. This can be of huge value in identifying the strengths and weaknesses in the material. It also can improve the product.
• Customer feed-back loops. Great products still require careful attention to customer satisfaction. It’s now possible to set up your documentation system so that customers can respond with their comments, questions, and suggestions. This enhances the customer experience, a critical factor in sales and marketing.
• Version tracking. Because XML document files become part of your source code or content management system, it’s much easier to follow the evolution of the content. Between the first draft and the last, did something critical get lost or misrepresented? Simply search the earlier versions.
• Shared content: At its most basic, every document contains copyright and contact information. If information changes, each of your documents must be updated. Who has time to go back and update PDFs? With XML content, this information can be maintained in a single file. Update that file, and you’ve updated all of your content.
• Collaborative development. The internet is a powerful collaborative and social tool. Because formatting is left to the stylesheets, authorized users can participate directly in the documentation process using a simple text editor. Using version control, tech writers and editors can see what changed.
• Access control. Access to content is more easily controlled. For example, user content can be more easily distinguished from System Administrator or Developer content. There is no longer a need to produce separate PDF documents.

There are a number of options for implementing web-based documentation. Choosing an implementation depends on the nature of the content, the version control/content management system available for organizing and tracking the content, and the desired output.  The more popular implementations are:

• DITA. This is more amenable to the specialization/definition of information/content architecture. It is better for massive collections of interrelated topics.
• DocBook. This was originally intended as a way to manage single books or articles. It’s better for projects that focus on a single large publication.
• CMS/Wiki. This allows collaboration on multiple unstructured content.

Interested in learning more? See our blogs An Introduction to XML and DITA, Technical Documentation Moves Toward Live Product Content, and Editing Equations in Oxygen XML Editor for more information.