What Makes a Technical Document?

When Communication Requires Education

After several months of back and forth emails, marathon telephone calls and several face-to-face meetings, we were in contract signing phase with the client. My associate and I sat in the spacious office and were meticulously pouring over the details of the contract that was about to be signed.

It was a long sought technical writing assignment for which we would create the in-depth policies and procedure manual that they obviously needed. After some consultation with their legal department and ours, we left the premises – contract in hand.

 We were happy with the conditions – total work done remotely, all subject matter experts were to be contacted through telephone or email and status reports, invoices and time sheets were scheduled for PDF creation.

 After the second week, the client had questions about the actual depth of the documentation effort. It was a classic case of lack of scope. In other words, he misunderstood the actual depth of what is really involved.

There are documents and there is Documentation. The former is a MS Word file and the latter is an actual functional specification that serves as a road map and instruction set for both the uninitiated and the experienced.

 At some point, we had to educate our client about the entire process. Through his own admission, he wasn’t as well-versed as he should have been and was tasked with this assignment in a brief fashion.

 Our good client now understands that Documentation of this sort may be composed of various components, some of which are:

• Document Styles
• This is critical. The format must be easily read and contain the appropriate amount of white space to minimize eye fatique
  
• Appropriate Navigable Table of Contents
• Indexes and Cross-Referencing
• Endnotes (Where Appropriate)
• Footnotes (Where Appropriate)
• A Content-Driven Focus and Theme of the Document
• This is probably the most crucial requirement. Often it takes a series of meetings among members of management, technical staff and clerical users to attain the correct focus of this effort
  
• Document Must be ‘Testable’:
• Where auditors are involved at a later step, the Document must prove to be accurate in its descriptions, references and procedures
• Document must be maintainable:
• Insure that the staff or those responsible can easily update
• An Online Help version (Recommended but not always necessary)
• This is equivalent to an Online Help File that stays in sync with the original document and can be referenced throughout the company’s intranet