In my technical writing classes, I often threaten to develop a style guide for that class alone. This would head off students before the blundered into common grammar and stylistic errors. So here it is.
1007 Technical Writing Style Course – Style Guide
You are really going above and beyond on the blog posts! Jason, really enjoyed your post today about Ottawa. In my experience, people are more apt to click through a link with a fun picture – so well done. Thanks for making my job easier (and more fun)!
—C.G.Koens, Implementation Specialist & Editor, Weaving Influence
(third-party provider to Webtech Wireless)
I recently wrote a corporate blog and came upon some interesting considerations. It’s one thing to write a blog for one’s own site, but to write on behalf of someone else (i.e., a company) is another matter. There’s of course the matter of style and tone, but what is appropriate especially if there are no clear guidelines.
You may have to spin things slightly to represent the best interests of your employer, but don’t be insincere—people sense it. The story I wrote, Iridium satellites not affected my recent solar storms, concerned the effects of recent solar storms on the company’s GPS location-based tracking services. I realized that it was important not to represent their technology as vulnerable or the solar storms as alarmist.
Here’s what I came up with:
- Focus on the positive – plays down concerns in the title
- In first sentence, I use end focus to draw attention to reliability of products/services of company “…has had no affect on Iridium satellites”.
- I chose a beautiful and re-assuring image of the aurora borealis, instead of something that might cause concern.
- I was given permission to use images found on the internet (always something to consider), but because I didn’t think the site where I found this image was one I wanted to highlight, I buried the source credit in the code for the image.
Discussing Style and Tone in technical documentation in the technical writing field is usually a one-minute conversation that really doesn’t even address core issues. Usually, the conversation is about style guides or templates (which has nothing to do with style) and tone hardly even enters into it.
Here are some quick definitions:
Style is the cumulative effect of choices about words, their forms, and their arrangement in sentences. Style is not just a decoration but rather is a atter of substance. Style affects comprehesnion and a reader’s attitude toward the document.
Tone is the writer’s attitude toward the reader as well as the subject matter. It describes the writer’s relationship to the reader—colleague to colleague or teacher to student. Tone also describes one’s own persona. Persona is the mask you wear as a writer. Do you see yourself as an authority on a given subject or an explorer sharing your findings. That’s tone.
Last night, I taught one of my best technical writing style classes ever. It’s funny, but I was super nervous before the class—I must have known I was destined for greatest (or something). I think what made the class go so well was that there was a consistent flow from introduction to final farewell that built on the idea that in order to write good technical documentation, you need to understand your audience. I even tied in or foreshadowed themes that I know I’ll be teaching in the ensuing weeks.
The flow from after the break from the card game (barnga) to the presentation on discourse communities to the final humorous presentation of the Grand Central Station freeze worked really well. They get it and they had fun getting it.
Next week, I need to find a way to incorporate the graphic I made a while back lampooning everything that’s wrong with technical documentation: