After many years of blogging, and consistent with my desire to move toward retirement, we have ended the Insights blog. Thanks to Doug Bedell for his years of blog support.

At the Holidays, Twitting Amazon

Posted on December 28, 2016
Filed Under Communication, Technology | Leave a Comment

Oh, the power of a good technical writer, or so it appeared. But hold on! Here’s a post on the Darth Continent blog on a “Starry Sky holiday light projector” that’s still available at Amazon.com, despite disappointing a technical-writer customer and prompting him to blog about it.

The projector was supposed to “spray” red and green lights on the writer’s home. “I purchased one of these through Amazon, and it didn’t take long at all to see why this particular product is no longer available,” or so the unfortunate technical guy thought. “Just one night after setting it up in my front yard, the green light disappeared, leaving just the red. Picking it up and shaking it gently yielded a disconcerting rattling inside.”

He disassembled the item, as any tech guy would likely do, and figured out how to fix it. But his parting rueful comment is: “Review products carefully and pick one that does what you want it to do but isn’t rife with poor quality control as demonstrated here.”

Unfortunately, a technical writer needs to know his source place, not just patronize it, to insure that he’s getting the results he expects. And (apart from Amazon and it’s mail-order business) it’s a tech writer’s job to prompt that sort of continually bright, end-result process. – Doug Bedell

Successful Cookie Baking – From Mom, an Acknowledged Expert

Posted on December 20, 2016
Filed Under Communication, Technology | Leave a Comment

How is technical writing like cookie baking? Bart Leahy raises this holiday-time question on his Heroic Technical Writing blog not so much in the interest of better cookies, but in reprising an oft-proven process for exemplary technical writing.

First, be sure you’ve consulted the experts in whatever process you’re recording. In Bart’s case, after he’d botched a couple of batches of cookies, they were his sister Colleen and, then, the source of the cookies he’d remembered so fondly, his mother.

When Bart’s Mom asked about the results he was getting, he replied, “Well, the cookies aren’t very sweet and (they’re) a bit flour-y tasting. Maybe a little salty.” He described the procedure he was using to get so unsatisfactory a result. After his Mom asked a few clarifying questions (“We walked through my procedures…”), Bart got his answer – he wasn’t using enough sugar and salt wasn’t included in his Mother’s recipe.

Yet Bart’s recipe had them both listed in the quantities he’d used. Clearly, it was mistaken. Bart had gone to an acknowledged expert, asked some clarifying questions and corrected a couple of details he’d gotten wrong.

And so, we’ve reached the core of the technical writing process: Consultation with experts and diligence in recording accurately what’s been learned. It can then be confidently applied by it’s intended users (but none too confidently, until confirmed in a few early trials).

When a technical writer gets to feeling expert himself or herself, that can be dangerous. A process doesn’t originate in the writer’s mind or keyboard, but in those who used it beforehand and smoothed it out for reliability on the scene. Being a good technical writer, as we’ve noted before, is much the same as being a good reporter. Or a good cookie baker, once you’ve gone back to the source of what you’ve been seeking to reproduce. – Doug Bedell

(Illustration: MidwestLiving.com)

Slides for a Tech Writer’s Craft

Posted on December 16, 2016
Filed Under Business, Communication, Technology | Leave a Comment

Wow, what a resource Google is! You knew that already, but here’s absolute proof from a technical writer’s perspective: From 2006, 10 years ago, we’ve come across, via Google, a set of slides on “Sentence Structure of Technical Writing.”

The slides are by Nicole Kelley, who in 2006, anyway, was in the Program in Writing and Humanistic Studies @ MIT. They apparently were some of her lecture materials. And they lead off with a quote from George Gopen and Judith Swan from The Science of Scientific Writing:

“The fundamental purpose of scientific discourse is not the mere presentation of information and thought but rather its actual communication. It does not matter how pleased an author might be to have converted all the right data into sentences and paragraphs; it matters only whether a large majority of the reading audience accurately perceives what the author had in mind.”

Accurate perception, of course, is especially critical in technical writing. Enough said about that particular point.

Ms. Kelley’s Google-enshrined thoughts go on to discuss Planning/Rethinking, Writing and Revising, key components of a tech writer’s craft. “Planning” includes “Know your purpose, Know your material.” Don’t start writing and guidance materials until you’re clear on who you’re trying to communicate with. If it’s, say, a power plant, it’s most likely the entire workforce, whose members have differing backgrounds and needs – as doesn’t anybody when you think about it?

So clarity and avoiding jargon come next. And they lead to a host of other timely principles, with examples. What a great, Google-summoned resource! There are 24 slides in all, and they amount to a one-stop education in productive technical writing. Have at them! – Doug Bedell

Email Subscribe

Recently


Categories


Archives


Blogroll