Monday, January 4, 2016

The Dirty Little Secrets of a Technical Writer

Technology journalist Michelle Bruno contributed today's post. She covers technology and face-to-face meetings in her weekly newsletter, Event Tech Brief.

One might marvel at how I, someone who literally cannot navigate the remote controls of the television set, can write about computer networks and software. It’s really very simple.

The first thing I do when confronted with a particularly complex project is avoid panic. I know now there will be a point at which everything makes sense. It’s just a matter of time.

If the client has not given me source materials, which is rare, I create my own library of research—pulling from Google Scholar or scientific journals and magazines accessed from the library of a local college (a benefit of being an adjunct faculty member).

Almost always, I print the resource materials out on paper and highlight them with a colored marker. As I scan, I begin to formulate an outline in my head.

If I become blocked or overwhelmed, I take a nap.

No writer, even the most experienced, can know everything about everything. That’s why subject matter experts are my best friends. Most software engineers or network administrators are interested that I’m interested and indulge my curiosity.

No matter what I write, every word on the page is still a part of speech: noun, adjective, verb, adverb and so on. 

For example, network, cloud, and machine are nouns. Virtualize, orchestrate, and provision are verbs. It’s critical to get everything in the correct slot.

Structure is very important to me. Even in technical writing, I try to make sure every opening paragraph gives the reader a clue about what they will learn as they read on. 

Every paragraph I write has a topic sentence. If I start out with a list in the first paragraph, I make sure the explanatory paragraphs in the body are in the same order as the items in the list. 

While attempts to be humorous or ironic are normally ill advised in technical writing, I still try to be elegant and clever. Words are still my children and I try to present them in the best light possible.

When I’m not writing, I read. I look for structure and elegance even in the most technical of articles. It’s a blessing and a curse.

I edit as I write. Most of the time I spend more time on the opening paragraph than I do on the entire article. I can’t get comfortable until my direction for the piece is set.

When I finish a project, I deliver it to the client and never read it again for fear I might find a comma out of place or begin agonizing over a word choice.

Technical writers receive exactly zero feedback. Most of the time, my efforts aren’t even acknowledged (one reason I blog). So, to get some warm fuzzy, I share the paper with my husband, who always says, “How the hell do you write stuff like this? You can’t even turn on the TV set.” I just smile.

Postscript by Bob James: Want a weekly dose of wicked good insight?

Subscribe to Event Tech BriefIt's free, and nobody covers the beat better

Powered by Blogger.