A Career in Technical Writing: Workaround

Bullet Points

  • A workaround is a procedure designed to overcome a shortcoming of a program or piece of equipment.
  • Sometimes the tools dictate the format of your work
  • Projects tend to go better if you have a plan (believe it or not)
  • Take the time to talk to the people on your project

Beating the system

Workarounds are common in the world of technical writing. They are the clever little solutions that you come up with because the program won’t do what you need it to do (hack is another term for this). In many cases, a workaround is needed because the program has a flaw. It is supposed to work a certain way, but it doesn’t. In other cases a workaround is needed because you want to make a program do something it was never designed to do. Workarounds aren’t just for hardware and software, they are for any situation in which you need to circumvent the established system. Workarounds are useful, and sometimes necessary, but they are never as good as a system that does what you need properly, and they are rarely supported.

After the success of the programmer’s reference, I wanted to put out a user’s guide. Of course, many of the problems that plagued my first attempt still had not gone away. I had no one telling me exactly what they wanted, and I still wasn’t sure what each report did or who it did it for. What I did have was the ability to take screenshots (images of the computer screen) and walk people through the process of filling out the pages needed to run the reports. I also had the information about what the output of the reports would be. By working with the main program (The main program was AMISYS and the report programs were custom written using SpeedWare) I started tracking down the variables as they corresponded to the report requests. This gave me some idea of what a user would enter.

Talking to people would have helped

Had I been more inclined to seek out the requesters and interview them, I surely would have come up with better information, but I was an introvert (according to my Myers-Briggs personality test I am INFP). The idea of tracking down strange people for information gave me an uneasy feeling with roots going all the way back to my daily beat-downs from schoolyard bullies as a kid (which thankfully ended when I grew to 6-1, 200 pounds by my freshman year in high school). My early days had taught me not to view strangers as friends, so I generally didn’t like to meet new people.

No one ever came along to ask how the project was going. Very few people, it seemed, had any understanding of what I was doing. The only people who showed any interest in my at all were the contract programmers. They would at least look at what I had written and offer advice, but none of them had a real stake in the outcome of my project. They were dealing with their own issues. Issues that I would soon get caught up in.

A simple plan

In the end, I came up with a simple format for the help. I documented each report with the following information (or as much of it as I had):

  • Name of the program
  • File name for the program
  • Short (one sentence) description of the program
  • Screen shot of the first screen
  • Long description of the program (about a paragraph)
  • Step-by-step process of filling out the fields
  • Additional screen shots as needed for the process
  • Description of the output

I’ve learned a few things over the years, and I’m sure I could come up with a better plan today, but at that point I was just happy to have a plan at all. This was a system that could have worked in Microsoft Word, although it would have been ugly. Microsoft Word does funny things when you add graphics. It tends to lose or move them, and it slows down dramatically. I had been pushing the company buy me FrameMaker for months (by this point I had grown to believe it could fix any problem), but the new FrameMaker required Windows 95 or Windows NT. The company eventually made the upgrade, and gave me my software, but by then I had a whole new set of problems to deal with. The work environment was about to change dramatically as I faced twin mergers, a new platitude-spouting manager and a programmer who hated my guts. Plus, I was about to say the word anal in front of the wrong crowd.

Further reading

Discussion questions

  • What parts of your personality get in the way of your success?
  • What are your tips for planning a project?
  • Do you have a favorite workaround?

6 thoughts on “A Career in Technical Writing: Workaround

  1. John, first let me say that I’m thoroughly enjoying this series. I’ve been pleasantly surprised by how many experiences we seem to have in common. I’ve had many jobs in which I found myself doing work that really wasn’t part of my job description, and I really admire your initiative to do whatever it takes to be productive.

    I’m an introvert as well and extremely uncomfortable with making “first contact.” I know that was my greatest obstacle in my most recent job. I might still be there if I had been willing to play the part of an extrovert and get information I needed to keep me busy. But, alas, it was easy to spend days holed up in my office without contact with anyone else in the bureau, and such an environment just made my shell thicker.

    In my current position, I don’t have the luxury of wallowing in my introvertedness. I am sharing an room with a coworker and I have zillions of meetings to attend, most of which I am expected to actively participate in. The good news is I’m working with a former employer and coworkers, not strangers.

    I often pride myself on my acting ability, my ability to appear as though I’m at ease with a group of strangers, but the acting takes a lot of energy and leaves me rather fatigued. And it’s not enough. I know I probably would be in a very different situation if I had not been painfully shy in my childhood and teenage years. But I can say for sure that I would be happier? No, and so I embrace my introverted nature and move on.

    I like the steps you used to document the reports. I used powerpoint and screenshots to walk my coworkers through the database I had created for documenting our programs. Screenshots are great, and I think the best manuals include them.

    I also had a similar experience using PageMaker and FrameMaker. Several years ago, I created a 100+ page report using PageMaker. Even though we had FrameMaker, no one in my section had received training on either so we were learning as we went. I was well into my report when a colleague showed what he was doing in FrameMaker, and I realized that I was using the wrong program. FrameMaker was different enough from PageMaker that I decided to not to switch software. I suffered but the report eventually was finished. Still, lesson learned: research the software to make sure it’s appropriate for your purposes.

    As far as workarounds … ? I’ll have to think more about that. Sometimes I think life is a workaround.

    Oh, and thanks for the teasers at the end of this article. Now I can’t wait for your next installment!

  2. Marie,

    It appears that you and I have even more in common. Later in the series, I will be discussing the persona I adopted for dealing with job interviews and other situations.

  3. Rhonda,

    I’m glad I could help you hark back. I’m not surprised you didn’t have the official title, small companies are more concerned with getting the job done than with formal structure.

  4. Love the graphic for the workaround, and I especially love the teaser in the last sentence!

    I’m enjoying this series – it’s bringing back a lot of memories of first starting out in this game in the early to mid-90s. I’d actually been doing the job of a technical writer for a few years before I knew it had a name. That’s what happens when you work as a lone writer in a small start-up where job titles don’t matter at first.

    Rhondas last blog post..What’s ‘national’?

  5. Pingback: Personal Essays on a Technical Writing Career — by John Hewitt | I'd Rather Be Writing - Tom Johnson
  6. Hi John, I’m really enjoying your series. As someone who also made the transition to being a technical writer in Tucson, your story hits pretty close to home.

    I have also been faced with having to document reports and I think the basic information I supplied was very similar to what you came up with.

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>