An Initiation into Tech Writing
When I began my first job as a tech writer, I was assigned to an office on the edge of the corporate campus, far from the IT department I was supposed to work with. The plan was that IT techs would send me rough drafts of procedures. Then I would tidy them up, work my tech writer magic on them, and turn them into a finished products.
After a week of sitting in that office, I realized, “Nobody’s ever going to turn in a rough draft!” Why should they? The techs all had their own jobs to do. They weren’t going to waste time on me. It was then that I realized that I had better get out and hustle up some business.
Being a tech writer is part writing, part investigation, and part soft sales. Determining documentation needs, getting cooperation from subject experts, and effective interviewing for information are as much a part of the job as writing and punctuation.
Nobody Wants to Read Tech Writing!
Nobody in their right mind wants to read a wall of text instructions. When a worker is faced with a wall of text, he typically starts “winging it,” making the written instructions a waste of time.
That’s why my tech writing generally focuses on visuals, outlines, and brief paragraphs. Good tech writing should be able to convey its message to someone who is only glancing at the document.
Process Awareness
It’s easy to become bogged down in the day-to-day running of your organization. When this happens, there are two important views you need to get–the big picture and the facts on the ground.
- The Big Picture
Flowcharts, workflows, and SOPs can help you visualize how your organization works and spur new ideas for a major re-engineering of your organization.
- The Facts on the Ground
Documentation of physical processes and software procedures, in addition to being useful training tools, can provide you with the fine-grain knowledge that will help you spot duplications of effort, potentials for confusion, and other inefficiencies.
Discerning Documentation Needs
Often it’s obvious what needs to be documented and what kind of documents will address the issue. Other times, not so much. An experienced technical writer can help you determine what aspects of your business need to be documented and what types of documents will best serve your needs.
Document Processes to get Credit for Your Work
At a hospital I once worked at, every doctor and department had its favorite software programs. These software programs were located on in-house servers in various departments on several campuses. In the course of my duties, I developed a list of all the programs, their experts, and the location of their servers. I did this mainly for my own benefit, but shared the list with my supervisors, who considered it harmless, but of minor importance.
Then our department was outsourced and my supervisors had to justify their jobs and expenses to their new employer. Suddenly my list became a critical tool for my superiors. “We have to service over 200 programs and 30 servers across 3 campuses! Here’s the list!” was their rallying cry. Documentation helped us all survive the transition.
Moral: Documented work is work you get credit for.
Documentation and the CYA Project
In real life avoiding blame, both legal and otherwise, can be as important as actual accomplishments. Nobody wants to be a scapegoat. Documentation can be an essential part of your CYA project.
When things go wrong and the finger-pointing begins, good policy documentation can mean the difference between being scapegoated and being exonerated. Good documentation—don’t leave home without it!
*Cover Your Assets
Keeping Documentation Updated
The map is not the territory–Alfred Korzybski
Eventually, even the best technical writing needs to be updated. Standard Procedures can update your pre-existing documentation, update our own documentation, or train your own personnel to make in-house updates.
STANDARD PROCEDURES 