What Makes Good Technical Documents

In this issue of Tips for Preparing Sales Documents, I have sought the help of Baruch Brodersen, one of the best technical writers with whom I have worked. Baruch understands the interactions between a product, its documentation, and the end user. I have been very impressed by documents he has produced and much of the following content stems from discussions over coffee and Danish.

Although my declared goal in writing these newsletters is to assist Israeli companies in developing their marketing and sales documents, many of my comments are equally relevant for technical documentation.

THE VALUE OF GOOD TECHNICAL DOCUMENTATION

In many Israeli companies, there is a tendency to begin thinking about technical manuals when the customer starts complaining. This is quite a widespread and very foolish attitude. Quality documentation can have a major impact on customer satisfaction. Poorly documented maintenance procedures can directly affect the maintenance of a product. Missing procedural steps, incorrect sequence of steps, inadequate procedures, and incorrect technical information and diagrams are all common issues. The more errors encountered, the more it costs your company to rectify the situation and the less likely that your customer will have anything positive to say about you, and the product you have sold them.

WHO SHOULD PREPARE TECHNICAL DOCUMENTATION?

If a developer has to write his/her own documentation, rather than a technical writer, you have a problem as developers do not have the time or the understanding of what is required. It will likely take longer, affect the release schedule, cost more (programmers earn more than writers) and, ultimately not turn out as well.

Many programmers like the idea of auto-generating documentation. Information is extracted from the source code itself, through comments. Programmers can thus use a common tool to create the source code and develop the documentation. This sounds great but the results are dismal. Don’t ever accept such rubbish as a substitute for good technical documentation.

WHAT MAKES A GOOD TECHNICAL WRITER?

Technical writing is the process of taking technical information and processing it so that it can be easily understood by the relevant readers. Good technical writers, by definition, must be technically adept and user-oriented people. They must be able to put themselves in the users’ shoes, anticipate their needs, and solve the problems confronting them. Acquisition of a logical and forward-thinking perspective is only the first requirement of an accomplished technical writer. He/she also needs a breadth of technical experience (software, hardware, business processes, etc.), expertise in tools of the trade, and a solid knowledge of English grammar and prose.

Sherlock Holmes would have been a superb technical writer. But a good writer is more than a sleuth. They must ferret out the information from the most diverse sources. They must dig into the brains of their subject matter experts (SME) who obviously have neither the time nor inclination to provide the necessary assistance. That is an accepted fact in Israeli organizations. Mastering the art of information extraction is a fine art.

HOW DO YOU EVALUATE A TECHNICAL WRITER?

I was asked this question by a former manager and I sent him the following points in response:

• The number of technical errors in a document (at the main review stage): Does the writer understand the product or the technology?
• The number of grammatical errors: Is the writer proficient in the use of the English language? I am quite serious. Half the people who call themselves technical writers should be sweeping the streets and not messing up documentation.
• Corporate style: Does the writer follow company guidelines?
• The number of technical support requests that the customer support team receives for issues that should have been addresses in the documentation.
• Adherence to deadlines: This is particularly important because it has an impact on the timelines of the entire release schedule of the product.
• Team work: Does the writer work efficiently with developers or other subject matter providers?
• Eye for detail: Has the writer identified bugs or other problems in the software during the documentation development process?

HOW DO YOU TEST TECHNICAL DOCUMENTATION?

Technical documentation deserves the same amount of testing and scrutiny as the product it purports to document. Usability testing is a very effective way to identify potential problems in technical documentation. The actual execution of a procedure will reveal how the tester’s understanding differs from the intent of the writer. Also, ambiguous language becomes quite obvious when a user is confronted with the task of translating written statements into specific actions. If the writer and tester work as a team they easily identify areas where their interpretations and understanding of written procedures differ and can very quickly rectify the situation – for the benefit of company and customer.

GET FEEDBACK ON DOCUMENTATION

Feedback from customers motivates writers. They enjoy being in the limelight. Furthermore, your documentation survey conveys a positive message to your customers. They appreciate being able to communicate their complaints and this gives you, and your writers, the opportunity to open a channel of discussion.

PROVIDE PRINT FOR CUSTOMERS WHO ASK FOR IT

Printed manuals are disappearing. Most companies provide PDF versions or online help only. Naturally this saves time and money. But it can be irritating for customers and self-defeating. What good is online help or troubleshooting software when the software won't run?

I suggest providing one printed set of documents with each system or delivery and if the customer wants more, it is their obligation to print from the PDF files that you have provided.