Technical Writing Techniques That Will Enhance Any Writing Project

I have been writing documentation for Axon’s integrated trucking and accounting software package for over 5 years. Certainly, software documentation is a specialized style of writing, but it has taught me some useful lessons that apply to any writing project.

Just do it!
We went live with some very rough, basic documentation almost immediately. And we’ve been revising it and adding to it ever since. I’m convinced that that was the best approach. Once we had the initial framework, we could start identifying what was missing and add to it. But we had time to get a better sense of what customers were looking for and the types of questions they were asking.

Far too often, writers are paralyzed by their search for perfection or completion. Our writing will never be perfect or complete – just run with it. Start writing the novel you’ve dreamed about for years. Your theme and your characters will evolve as you write, but now you’ve got something to work with.

Break Down Complex Tasks
Axon Help is available in several formats. We provide explanations for all the principal fields on a screen. But we also provide How do I that outline, step by step, how to carry out a task. I’m guessing that these are the most valuable portions of the Help for many users as they can see how it relates to what they are trying to do. For example, How do I enter an Order? or How do I pay an Owner Operator? or How do I complete a bank reconciliation?

Format can make a big difference. The step-by-step layout means that customers can work through a complex procedure one step at a time rather than having to understand everything all at once, and we can integrate information from a number of different screens.

Know Your Audience
Axon has just introduced an additional section of Help for new users because we recognized that they were the primary users of the Help – both when setting up the Axon system and during their first few months of using it.

We’ve packaged the Help so that it is easy for new users to find and to use by placing it in a separate section and breaking it down into sections and checklists. There’s a month-end checklist to help the accounting staff as well as step-by-step explanations of some of the initial tasks (My First Equipment Statement, My First Payroll).

I’m now identifying a secondary audience – Axon’s staff who are using the documentation for training and orientation and for answers to questions they haven’t encountered before. Although they will never be the primary audience, it does provide an added incentive to make sure that the Help is accurate and comprehensive and as up to date as possible.

The lesson to be learned – your audience may change over time, and you may have more than one.

Get More Than One Opinion
I interview programmers, support staff and trainers when I’m preparing the Axon documentation. It would be so much simpler to just work with one person all the time. But no one person has all the information. The programmers can tell me what the software is designed to do, but it’s the support staff who tell me how customers are actually using the program and the types of problems they are having.

As a technical writer, my job is to reconcile the different perspectives and to maintain a focus on what the customer needs. I’m an intermediary, trying to understand and interpret both staff and customer needs.

A writer should be an independent observer, aware of both the people who are being interviewed and the audience who will receive the information. The two groups may have wildly diverging interests and points of view. It’s up to the writer to weave them together.