Skip to main content

Tag: technical writing

Opinion

Training new hires in technical communication

After an arduous job search process that took place during my senior year in the Professional and Technical Writing program at Virginia Tech, I was recently hired here at Scriptorium. One thing I have learned is that matching candidates, especially new college graduates, and jobs in the world of technical communication can be difficult.

Read More
Opinion

Tech comm skills: writing ability, technical aptitude, tool proficiency, and business sense

Technical Writing is only about what software you know! Is that why every where I read any type of document, web page, or article it is FULL of misspellings, incorrect punctuation, and horrible formatting?!!

That’s what started a thread on LinkedIn that encapsulates long-running debates on the skill sets technical writers need. (The thread was removed from LinkedIn sometime after Friday, unfortunately.)

Read More
Opinion

Cardinal sin of blog (and technical) writing: making the reader feel stupid

Want to get me riled up? You can easily achieve that by making me feel stupid while reading your blog.

I read a lot of blogs about technology, and I’ll admit that I’m on the periphery of some of these blogs’ intended audiences. That being said, there is no excuse for starting a blog entry like this:

Everyone’s heard of Gordon Moore’s famous Law, but not everyone has noticed how what he said has gradually morphed into a marketing message so misleading I’m surprised Intel doesn’t require people to play the company jingle just for mentioning it.

Well, I must not be part of the “everyone” collective because I had to think long and hard about “Gordon Moore’s famous law,” and I drew a blank. (Here’s a link for those like me who can’t remember or don’t know what Moore’s Law is.)

Making a broad generalization such as “everyone knows x” is always dangerous. This is true in blog writing as well as in technical writing. In our style guide, we have a rule that writers should “not use simple or simply to describe a feature or step.” By labeling something as simple, it’s guaranteed you will offend someone who doesn’t understand the concept. For example, while editing one of our white papers about the DITA Open Toolkit, I saw the word “simply” and took great delight in striking through it. From where I stand, there is little that is “simple” about the toolkit, particularly when you’re talking about configuring output.

Don’t get me wrong: I’m not saying that a blog entry, white paper, or user manual about very technical subjects has to explain every little thing. You need to address the audience at the correct level, which can be a delicate balancing act with highly technical content: overexplaining can also offend the reader. For example, in a user manual, it’s probably wise to explain up front the prerequisite knowledge. Also consider offering resources where the reader can get that knowledge: that way, you get around explaining concepts but still offer assistance to readers who need it.

In the case of online content and blog entries, you can link to definitions of terms and concepts: readers who need help can click the links to get a quick refresher course on the information, and those who don’t can keep on reading. The author of the blog post in question could have inserted a link to Moore’s Law.  Granted, he does define the law in the second paragraph, but he lost me with the  “everyone has heard”  bit at the start.

That “everyone has heard” assumption brings me back to my primary point: don’t make your readers feel stupid, particularly by making sweeping assumptions about what “everyone” knows or by labeling something as “simple.” Insulted readers move on—and may never come back.


Read More
News

Tech Writing 101: Now certified as excellent

Happy news in my email this afternoon:

The STC Carolina chapter has completed judging of the 2009-2010 Technical Publications Competition. For your Technical Writing 101: A Real World Guide to Planning and Writing Technical Content (third edition) entry, you have received an Award of Excellence. Congratulations on your accomplishment!

Congratulations to Alan Pringle, who did most of the work on the 3rd (and previous) editions.

You can order the book at amazon.com.

Read More