Technical writing is often a mess. It doesn’t have to be even if the written word is a medium subject to individual interpretation.

Author Stephen King said that writing is psychic communication. I’m writing this on a remote county road in Central Texas beside a winding creek. You’re reading it many miles distant in a very different setting, yet thoughts composed here at creekside appear in your mind. It’s magic.

When that magic works, it’s because the writer did his job. 

Part of the secret comes from the writer knowing his audience. Documentation for doctors should assume they know the difference between hypo and hyper. Instructions for a database extension for medical software probably shouldn’t make similar assumptions. DBAs working on medical databases probably aren’t going to be medical professionals, they will be database professionals.

If there is any doubt, list additional reading or courses of study to enhance understanding. If such sources don’t exist, consider writing them.

Fiction has a single mission, to tell a story that will move the reader. Technical writing often has two objectives. It has to introduce a new reader to your subject and it has to serve as a reference for those who already generally know what you’re talking about.

The first goal is best accomplished by engaging the reader’s imagination. Put the reader in situations where your product will save the day. The more food for thought the reader has, the more the reader will learn.

Your document’s usefulness as a reference comes from organization. How logically subjects are grouped is a big part of that, as is the completeness of your cross references.

Any authority on technical writing will tell you documentation has to be clear. How that’s done isn’t generally detailed. That’s a shame. Most documentation suffers from a few simple shortfalls.

Never document how to do something without providing at least a hint of what reasonable goal is accomplished. Why you would want to do something can be more illuminating than the nuts and bolts of how you do it.

Never lead users into traps. When you explain how to do something, always explain how to undo it.

Your reader will gain more insight into changing the state of the system you’re documenting. Even better, the reader will gain confidence in the product and be able to explore.

Along with documenting operations as complimentary do/undo pairs, include information on side effects. If something is a one-way process, highlight the limitation.

Design criteria, at least some of it, is of great interest to users. Knowing why something was designed the way it was gives insight into how it does its job and what limitations may have to be observed.

Novelists create believable characters by following forces like goal, motivation, and conflict. A technical document can benefit from similar ideas. Conflict is not generally something you want between a user and a product, but goals, motivation, and resources make nice touch points.

• Goals – What can the user do? Illustrate by example with suggested work flows.

• Motivation – What drives users of your product? Illustrate how the product fits its mission.

• Resources – This is of long term interest. Remember the original (nice) definition of hacking from 1960’s model railroad enthusiasts. Hacking was the use of mechanisms for things their inventors did not predict.

For instance, I recently needed to extract and format a report from a Kanban-like organizational utility. The software exported several formats. Nothing matched what was needed.

I used the software’s option to export comma separated values. From there, a mail merge in a word processor produced the report as a series of index cards. I could have created a much more elaborate solution, but the mail merge did an acceptable job with almost no work. Further effort wasn’t justified. We got the report done with minimal effort.

The Kanban package wasn’t a contact manager. The word processor wasn’t a report formatter. Success was possible because basic resources in both packages were known values.

Don’t just tell me what you think your product is good for. Tell me what it does so I can use it for purposes you never envisioned.

Plan for successful documentation by outlining and concept mapping. As the document evolves, keep the outline and concept maps in lockstep with your work and with the product. Present features in a logical order in which to learn the product, and organize the reference aspects of your document according to concept.

Write for the purpose of communicating with your intended audience. Internal documentation should focus on product requirements and internal resources. UI/UX requirements must be clear to all team members. API, class methods, and class attributes should be available to interested parties.

For consumers, focus on the product’s mission and illustrate its use.

In all cases, plan, edit, and revise, much like the software developer’s write, compile, and debug cycle. The more time spent planning, the less needed for edit and revision and the easier future revisions will be.

Thanks for visiting. If I can be of service in your organization, either for software development or technical writing, don’t hesitate to reach out with the Get in Touch! link above or by email to carl@carlhaddick.com.

If you want to see samples of my technical writing, download any of the coding examples on this site. Each example is in a zip file containing source code and PDF documentation.