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.

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 


Leave a Comment

If you would like to make a comment, please fill out the form below.

Name (required)

Email (required)



Email Subscribe