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.

Clarity In Progress

Posted on January 31, 2016
Filed Under Business, Communication, Technology, The Writing Life | Leave a Comment

Who would disagree that the biggest issue in technical writing “is the inability to see simplicity in complexity.” If you’re trying to reach even a veteran engineer with guidance or instructions on a new procedure or process, you want to be as direct as the process allows.

We thank Mark Crawford on the ASME.org site for discussing this question of simplicity in complexity via his “How Engineers Can Improve Technical Writing” post. It’s been out there a few years now but, as we suspect may be true of other colleagues, we’ve just caught up with it in the Internet’s vastness.

To write with clarity and directness requires that you understand a technical situation as fully as your capacities allow. We assume you wouldn’t be writing about such challenging material if you weren’t qualified to do so. The issue isn’t technical competence so much as communication prowess. You need to describe a process clearly and competently. When you think you’ve finished, the test is, Have you communicated well?

“After all,” Crawford adds, “technical writing is not just about language skills – it’s about how we think.” Indeed. Clear writing requires clear thinking. And that’s as much a communication issue as a technical one. You can’t communicate well if your thinking is garbled at the gate.

So before plunging into a process, take time to review it first. What is it intended to accomplish? How can a reader/user get there promptly, clearly and safely? Simple sounding, yes, but not so simple in practice. Often we’re too rushed, or feel so, to
organize, settle down and produce a clearly described series of steps to get there as intended. – Doug Bedell

Instructions As Music Rather Than Noise

Posted on January 19, 2016
Filed Under Communication, Technology | Leave a Comment

Effective technical writing (as all forms of writing) begins with the desire, and ability, to communicate well. What’s that mean in the technical realm? As always, to be focused, first of all, on your audience. Who will be using, and hopefully consuming, your writing, in the form of instructions, plans and aims? Do they have infinite patience? Probably not.

Your readers are more likely to be people in something of a hurry to use the instructions at hand to get to a desired end. It’s the end, not the instructions for getting there, that matters most. Sure, they shouldn’t be hurried. But if instructions or explanations don’t produce a prompt result, your readers are likely to feel harried rather than engaged. Your call on which is the more likely.

Let’s turn to an example from outside the technical realm – listening to music. At a concert, a listener’s aim is, hopefully, to be elevated by a performance. (In a technical setting, it’s to be satisfied with an outcome.) What does the concert goer have at hand to be ready for an inspiring experience. Most likely, the program. It functions as a sort of technical manual for the occasion, at least an introductory one.

“Programs,” writes Aarik Danielsen in the Columbia, Missouri, Daily Tribune, ” are helpful guides to the repertoire about to be performed; sometimes they include revealing program notes about composers and their muses.

“But,” he adds, “they also tend to include a great deal of fine technical details that wow the initiated but otherwise read like a foreign language. There are often dry lists of performers’ credits and educational achievements…” Such “resumes,” as Aarik calls them, “are meant to establish a pedigree but can up the intimidation factor for audience members.” So avoid them, they’re not necessary to the end in view – enjoyment of a concert, or in a technical setting, accomplishment of a task.

“Often, a concert program,” Danielsen warns, “reads like something written by the academy for the elite, with little to offer by way of illumination for the ‘common’ listener.”

So consider whether the technical writing you’re embarking on will be music to a user’s ears, or a passport to a jarring jungle of details. The difference is readily within a good writer’s ability to discern and correct, as appropriate. One will be satisfying music, and the other, more like annoying noise. – Doug Bedell

Clarity In Progress

Instructions As Music Rather Than Noise

Recently

Categories

Archives

Blogroll

Find It