By Ramana Murthy

Technical communication: Content is the key

Recent years have seen more and more capable authoring tools with an ever-increasing number of smart features. But what about the art of writing good content? Has the focus on highly-developed software applications shadowed the need for writing comprehensive, high-quality content?

Software documentation was developed to assist users in applying software solutions. Initially confined to the printed book, documentation has now evolved into multiple forms, all of which fall into two main categories: softcopy help, which is often integrated in the software, and hardcopy help.    

As documentation has evolved, authoring tools have also become smarter. RoboHelp, FrameMaker, Doc-To-Help, HTML Help Workshop and Author-it are just some of the currently popular authoring tools. These tools come with features such as automatic index generation, content storage in a relational database, web publishing, text import/export to XML, and so on. They make content reusability and maintenance easy. The current state-of-the-art in technical documentation are ‘single source’ authoring tools that produce multiple output forms from a single source of content.  

Tools above trade?

Apart from the obvious benefits of these tools and their features, their popularity has an undesirable side effect. Some of the younger technical writers are so taken with these software applications that they are equating the cleverness of these tools with successful technical writing. They are placing the tools of the trade above the trade of writing and ignore the more important objective of content. It is no longer fashionable for a technical writer to claim that he/she writes in Microsoft Word. Instead, it has to be one of these smart tools or something even more futuristic. It seems that in order to find employment, the more such tools are listed on the resume, the better. At technical writing forums and conferences, as well as in user group discussions, talk is usually centered on emerging tools and technologies, metrics in technical writing, the Agile methodology, and so on, but rarely on content development and quality. As a result, a majority of technical writers are tool-savvy but not content-conscious.     

A good product documentation is one that helps users achieve their goals easily, irrespective of the tool it has been authored with – be it RoboHelp, Author-it or the unglamorous Microsoft Word. Product documentation does not arrive with a label like “Developed with the best documentation tools”; nor are there instances of customers preferring product documentation authored with a particular tool.   

Surely, these tools provide great benefits, but they cannot create content (at least not yet), and fancy features are not a substitute for good content. Content still has to come from the writer, and can then be made more usable and navigable with the help of these tools. No amount of flexibility and navigation features can make up for a lack of good, accurate content. All those hyperlinks, hide/show paragraphs, and quick search features may help the user jump up and down a document but he will remain frustrated if the information he was looking for is not available or incomplete.

Value chain impact

We all have heard of specialty food joints that do roaring business by serving a unique, hard-to-imitate delicacy. To stay in business, technical writers should be like the chef who whips up the tasteful dish – the prime mover of content. Rather than trying to become tool experts, technical writers should aim at producing better content that can add value to each stage of the value chain. Better documentation means less support calls, more cost-effective translations to other languages, more sales and so on.   

This also has a positive side effect: technical writers who are good at content creation can also contribute to marketing collaterals, newsletters and other communications that a company needs on a regular basis.

Key points

Creating strong and meaningful content is no easy task and it differentiates the professional from the amateur. To make a real contribution to the documentation, the technical writer should be well versed with both the product function and its business need in the market. A technical writer who wants to make a difference should remember the following:

• Know thy product well. You cannot describe a product (or a place!) that you have not seen.
• Develop a good document structure. You should be able to judge what to include and in which sequence, and what to leave out. 
• Judge the level of detail required for each topic; there is no point in describing everything at every instance. 
• Identify the topics that need to be supplemented with “More Info” links and cross-references. Do not provide cross-references for every topic—it is like providing road signs all along the way.  
• Create appropriate index entries. Redundant index entries are a waste of time and resources; thumb rules like “at least two index entries per topic” only increase the document size, but don’t help the user.  
• Write in a simple and flawless language. You don’t need to impress the user with colorful prose; plain is okay. 
• Revise, revise, revise. Until a document is going to be put on the shelf, repeat all of the above steps as a loop.
• Go beyond and enrich the content. The company’s documentation standards and practices cannot cater to every situation; try to figure out the unique documentation needs of the product and fill in the gaps.  

Of course, in addition to providing excellent content, if the writer is also a tool whiz, it’s even better. But if not, no worse. Tool expertise can be picked up along the way: you can learn to use a feature when you actually need it. Some companies have successfully implemented an optimization model: the senior, more experienced writers do the content creation (and go on to become subject matter experts) while the juniors take care of tasks like creating a bookshelf, publishing different outputs from a single-source tool, porting content from one content management tool to another, and so on.  

Content as core

A good number of customer issues in a software company are usually due to poor product documentation. This has a chain effect that finally results in a large support team, which not only leads to increasing costs but also to an increased work load for the company.     

To prevent the domino effect, technical writers should know their craft, not just the art of using authoring tools. The argument is not for ignoring emerging technologies that make life easy; rather, it is for producing excellent content so that tools and technologies are put to even better use. The software industry has ever-shifting preferences and will move on to newer and fancier tools, dumping the current ones. A technical writer who confuses the mastery of authoring tools with the mastery of the profession will go out with the tool.

Remember the dotcom bust? So many dotcoms went out of business not because there was a dearth of web page designers but because there were not enough content providers. Technical writing is no different: you cannot script a success story for a product with cool tools and cold content.