Bullet points
- Struggling to make the wrong tool work for a job can add months to a project
- FrameMaker is good for long technical documents
- PageMaker is good for sending a newsletter to your Aunt Fanny
- Sometimes the most important thing a technical writer can do is gather information
- When expectations are sufficiently low, it’s easy to be a star
Meet your Maker
I wish I could say I got off to a running start and quickly proved my value at my new job, but this is about my real career, not my resume. Life at PHPS did not begin with a bang. No one really knew what they wanted me to do, and my equipment wasn’t exactly state-of-the-art. I was hoping for FrameMaker, but I got PageMaker instead. The two products sound similar, but there is the world of difference between them. PageMaker wasn’t designed for long documents or technical material; it was designed for creating newsletters and flyers. I knew the product pretty well from my days working as an editor for a small newspaper, and I knew it wasn’t going to do anything I needed it to do. That didn’t stop me from trying. I designed a few pages of how-to materials, but the process was slow and tedious. Before I knew it, three months had passed and I really hadn’t produced much of anything. It was at that point that I decided to change course.
That report has a lot of fans
I had spent a lot of those first three months reading code and looking at output. Both the code and the output came on long bands of fanfold paper. You don’t see it as much anymore, but back then most reports were printed on page after page of green and white paper held together (and in order) by perforated edges. For some reports the code ran only half a dozen pages or so, but others ran much longer. As for output, that could go on for hundreds of pages, but I rarely needed to see much beyond the first and the last page. Those were the ones with the column headers and the totals.
Sometimes your audience is just a cube away
After three months of banging my head against a monitor trying to develop something for the end users, I gave up on that and decided to create a reference manual for the programmers. I wasn’t sure if it would be useful, but there was no one to tell me not to do it, so I just switched gears and started putting something together.
The reference manual was far from pretty. I created it using Microsoft Word, which could handle text just fine, even if it fell short on the artistic end. I went through the code for each program and documented the one thing I was sure the programmers would care about — the variables. Every program had a list of variable names somewhere in it, which it used to call up information from the database. In addition, the program code listed the header information and the column names for the output, so I documented those items too. I also had (from the interface) a list of what programs were used by which departments, so I recorded that. If I had any other information, such as someone’s description of the report, I plugged that in too. All of these items together started to look useful, so I showed it to the programmers.
Believe it or not, I’m on top of the world
The programmers were ecstatic. They loved it. Without knowing it, I had created exactly what they were looking for. They could now look over the reference and figure out if an old program could be turned into a new one because it shared enough key information. This would really speed up the programming process, they told me. I was a hit, but I felt a little guilty. Creating this really wasn’t that hard and I didn’t do any real writing. All I did was gather information. If I had known that this was what they needed, I could have given it to them three months earlier. I didn’t say this, of course. I just went back to my cube and tried to figure out what to do for the end users…
Further reading
Quick Reference Guides: The Poetry of Technical Writing by Tom Johnson: An excellent guide to condensing a manual down to a two-sided piece of laminated paper.
How to Get a Lot Done – 7 Tips to Achieve More by Collis Ta’eed: Planning, teaming, delegating… give it a try.
Discussion questions
- How do you set goals for an unfamiliar project?
- When a strategy isn’t working, how do you know when to scrap it?
- How do you handle praise?
Comments on this entry are closed.