Friday, May 30, 2008

No product is complete till its paperwork is done

By Arun Jain, founder and president of Bay State Documentation

It wasn’t long ago that all user and technical documentation was developed as printed material. Users attended training classes and then used documentation as reference. Typical product life cycles were five years to 10 years and translations were rare. 

Obviously, today’s reality is quite different. Product life cycles are measured in months, not years. Products are frequently developed for global audiences. There is immense pressure to reduce support calls. Challenges such as these are redefining the design, development and delivery of modern-day documentation. Let us review some trends.

Designed for searching, not reading
The Web has trained us to find information instantly. Users expect this from their documentation as well. Online help is ideal for searching. Properly designed PDFs also provide search capabilities. But you cannot find what does not exist. Quite often, user documentation does not contain content that users need. It describes the product, not how to use it.
User-centric content is organized around tasks that users need to perform. For example, if a user needs to add, remove and configure ports, content topics should be “adding a port,” “removing a port,” etc.

Designed for global audiences
Achieving global market share requires translated documentation, which is expensive. But translation costs can be reduced with proper design. Use fewer words by documenting only what is necessary. Use fewer screenshots, because redoing screenshots for each language is expensive. Topic-oriented content can also reduce translation costs.
At times, however, translation may not be an option. In such cases, writing in simplified English makes content easier to understand. Use of drawings and diagrams is always helpful.

Designed for non-users
Increasingly, products are being integrated with others to form a complete system. Developers need to understand the programming interface that allows one product to communicate with the other. This type of information is contained in developer or application programming interface (API) documentation. API documentation is not new, but with increasing collaboration and integration, API/developer documentation is taking on a new importance. Writing API/developer documentation requires a technical background in the technology you are documenting. 

Structured authoring
In traditional documentation, content and formatting rules are manually enforced. This requires an enormous effort at the time of publishing.  Most writers can share horror stories about late nights tidying up final formatting.

Structured authoring defines and enforces documentation rules or “structure.” Templates for all publishing formats are predefined and machine enforced. That separates the task of content creation from final publishing. Not only does this save on development cost, it shaves off precious time at the time of publishing.

Structured documentation is supported by most authoring tools. A recent practice is to develop structured documentation using XML. XML-based documentation provides additional benefits and takes automation to the next level, significantly speeding up the process.

Modular content
Reusing content for multiple documents, or “single sourcing,” is the Holy Grail of content creation. This is difficult to achieve. You start with content, paste it into a different document and then customize it. But once customized, it becomes separate content — not easily reusable for anything else.

A recent trend is to develop content in small chunks, or “topics,” and then combine the chunks to create meaningful content. Key content is developed only once, saving significant time and money. With the acceptance of DITA (Darwin Information Typing Architecture) as the standard, this trend is starting to take hold. Topic-based content also provides enormous savings for translation costs.

A multinational corporation moved to topic-based content development. By developing 3,500 chunks and reusing them in 65,000 places, they were able to increase the number of documents produced by 250 percent, while reducing their staff by approximately 40 percent. 

Quality user and technical documentation is critical for the adoption of your product. Best practices make a big difference in your development costs and time to market. With just a little planning, you can transform your technical documentation from a headache to a competitive edge.
 
 

Arun Jain is the founder and president of Bay State Documentation of North Andover. He also serves as vice president for STC Boston, a global organization for technical writers. He can be reached at ajain@BayStateDocs.com or 978-852-7019.