The Joys Of Technical Writing

If you are a professional engineer, particularly one with a known interest in writing like me, you may be assigned to one of the more dreary forms of writing, technical writing. This can be anything from a project proposal, to a quick start guide, standards document, or the dreaded user manual.

I’m in the middle of drafting one user manual and updating another for my job.

But writing for a technical audience doesn’t have to be boring, and a lot of the tools that may work for your fiction writing project can be applied to your professional life as well. Here are a few tips and tricks I’m trying as I work on this latest “book”.

1. Keep using word count goals – Since writing a technical document can often involve a lot of external work, like taking screenshots, testing procedures, and fixing bugs, this word count goal may be more modest than you think. 1000 words of technical writing may be the equivalent of 3000 words of fiction writing for you. Whatever the ratio is, it’s easier to feel like you’re making progress against what can seem like a gargantuan undertaking if you keep these micro goals.

2. Don’t work too far ahead – There might be a temptation to use your afternoon taking screenshots and planning out the next chapter, rather than continuing to write. Sometimes this is fine, as it gives you an idea of the direction of your next section. But if you want internal consistency in your screenshots, and to show your procedures as a logical progression of one step to the next, you may be better off taking screenshots concurrently with your writing so you don’t have to do as much rework. This can seem disruptive to the writing process, but it reduces the amount you’ll have to go back.

3. Tell a story – If the piece of software is used to build something else, create an example project and use that project throughout the entire manual. Show how each chapter adds features to your project along the way. Be sure to explain everything you think needs explaining, but provide a context for that feature as well. It’s the whole showing not telling thing.

4. Have a little (appropriate) fun – I’m a math geek if you hadn’t guessed so you’ll see more than a few apt puns in example names in my technical writing. A common programming trope is the “Hello World” program or variable names of foo and bar (though these may not be appropriate in all professional contexts). As long as these puns aren’t excessive, and don’t detract from the overall usefulness of the document, they can be a way to make the writing more fun for yourself.

5. Have something else to do – As a software developer there are always bugs to fix and features to tweak. It doesn’t hurt to have a few of these in your back pocket to work on when you really don’t feel like writing. If you have a deadline, be sure you meet it, but make sure you get your brain thinking in different ways too. It will improve both aspects of your work. If you don’t have additional projects of your own, see how you can help someone else (again caveat emptor as your work environment may vary in terms of your freedom of development time).

6. Outline and write sequentially – A user manual will often be referred to in any order, so it’s important that each chapter be able to stand on its own. An outline will give you a sense of what other chapters to reference that are relevant to your topic, and writing sequentially allows for the continuing narratives of examples and back references to topics you’ve already discussed.

7. This is a living document – A fiction writer is used to the idea of revising and revising until something is done. Technical documentation (if it’s to be useful) is never really done. It has versions and revisions like software, and should be periodically updated. That’s why it’s important to have a structure you and others can follow so finding the sections to update is much easier.

What kinds of writing do you do in your professional life?

1 Comment

Filed under Trube On Tech, Writing

One response to “The Joys Of Technical Writing

  1. One of my writing challenges is the dreaded report, one of which I should be writing even now

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s