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.

Technical Writing Defined as a Challenging Task

Posted on July 27, 2016
Filed Under Communication, Technology | Leave a Comment

Technical writing is part of the broader field of technical communications – and what, precisely, is that?

Well, TechWirl explains that technical writing is “a field within business communications (that) encompasses a range of disciplines that work together to communicate complex information to those who need it to accomplish a defined task or goal.”

That’s a bit of a mouthful. Technical writing comes down to communicating technical information to those who need it to accomplish something challenging to them or their colleagues.

Yes, technical writing isn’t merely writing and it’s not simply instructions – it’s directional information for getting something done in a challenging context, an assignment that typically requires step-by-step instructions.

Consider technical writing as like producing a guidebook, or at least a pamphlet, with information on getting something challenging accomplished safely and satisfactorily. It’s not simply calling on a muse, a goddess presiding over a particular art, as the dictionary puts it, but providing a pathway to safe, efficient accomplishment.

Sort of like the directions for negotiating a yellow brick road, you might say, if you’re feeling a little lighthearted as you sit down to lead the way to the Emerald City. – Doug Bedell

Photo via Pinterest

Curiosity: A Reminder Of Ever-Present Opportunity

Posted on July 18, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Here’s a timeless technical writing post that we’ve kept in our folder and, in a summer lull, consider highly appropriate to share on a blog that aims to promote excellence in technical writing.

Sharon Burton posted it in June, 2014 under the heading, “The most important trait of a technical writer.” What do you think that would be?

Let Sharon answer: “I can teach someone to write. I can give them the Good Writing Guidelines, I can set up a structure that they need to follow to create topics. I can teach the basics of any tool we choose. I can teach them about audience and what the audience needs and how that impacts us.

“What I can’t teach is the curiosity to ask questions, to poke at the product, to constantly ask “What if…?”

There it is, “Curiosity to ask questions…” Why be curious when you’re writing about something that already exists, a process or product that requires a procedure? Because nothing is ever fully finished, complete, beyond evolving a little or a lot, beyond posing a risk of misuse or misunderstanding.

These latter categories are a technical writer’s great opportunity – to promote evolution and to ehhance safety and utility. “Nothing is ever fully finished” – therein lies great opportunity or, at the least, relief from carefully practiced, workaday routine.

Every topic or procedure a technical writer approaches ought to be treated as a learning opportunity with a paramount aim – freshness, newness, a better way of proceeding.

“If you’re curious,” Sharon advises, “you’ll learn more about your tools. You’ll ask more about your audience. You’ll think to ask important questions about the product you’re documenting. You’re thinking about everything as you do it, to understand more deeply everything you work with.”

Yes, technical writing is a form of exploration. You need to know the territory before you can bind it for others to follow safely and efficiently. So don’t ever leave unanswered a question that you or others raise – that might keep you from discovering something additionally important, something that needs to be included for completeness.

We’re glad we held on to Sharon Burton’s ever-pertinent reflections to this summer day when not much is, or seems to be, happening. – Doug Bedell

No ‘Catch-Up’ Practiced Here

Posted on July 8, 2016
Filed Under Uncategorized | Leave a Comment

Yes, technical writing can be a stressful trade. “No one likes being told what to do,” Anne Gentle writes on JustWriteClic.com. Well, yes and no. Employees subject to the dictate of technical procedures may realize that it’s they’re job to pay them heed, but may also be subject to other pressures to get their tasks done and put the rule book back in the drawer.

So tech writers need to develop a mindset in which they are both public relations people (in the best sense of “relational”) and rule-makers in terms of explaining how safely and efficiently to get things done in challenging settings.

That’s no narrow charter – being kind and promoting accountability at the same time. Timeliness is part of the answer. Colleagues will pay greater heed to information when it reaches them in a timely manner. For one thing, that makes it fresher all around.

“When a bit of code changes that makes a difference in the docs,” Anne writes, “that’s a crucial moment for influencing a particular behavior. The behavior we want to see is writing documentation while the code is fresh in your mind.” Code or any other pertinent change in a safety, procedural or security change in a workplace setting, we’d add.

Don’t wait to be helpful (we’d hesitate to say “directive”) – get the new word out as promptly as possible.

Striking while the “digital” iron is hot is what’s involved here. When people feel they’re being informed in a timely manner, they’re likely to act in a more prudent, compliant manner. The alternate is risking having them act hastily, with material that feels like playing catch-up.

No one in a workplace or at a website that needs technical writers in the first place should want to instill encourage playing “catch-up”. That’s what Anne Gentle has inspired us to advise. – Doug Bedell

Technical Writing Defined as a Challenging Task

Curiosity: A Reminder Of Ever-Present Opportunity

No ‘Catch-Up’ Practiced Here

Recently

Categories

Archives

Blogroll

Find It