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.

Don’t Fret Over Procedures That Flit By

Posted on June 28, 2016
Filed Under Business, Technology, The Writing Life | Leave a Comment

Just when you thought you’ve gotten into a groove in technical writing – crisp, informative sentences and paragraphs – comes a post proclaiming that s&p’s aren’t really the setting that matters any longer.

Yes, you’ve now got to learn video, 3D and other animated forms of advice giving, says IAM Consultants, Ltd. in Lithuania. (Go to their page on “New trends in technical writing.”)

The “second major trend” says IAM (the first is producing text in downloadable copies), “is that users easily accept visual rather than text type information. Assembly instructions, operational manuals, software interfaces everything is now rather to be explained in video or 3D rotatable objects than text…”

Does Disney have a technical writing branch? That might be worth checking out.

Seriously, making instructional matter as engaging as possible is a worthy goal. But the age of text hasn’t ended, hardly. It’s being amplified, perhaps, by appealing videos, but there’s still no substitute for clear, cogently presented text and diagrams.

We need here to make a distinction between technical writing as instructional material for consumer products and procedural guidance in factories and other actual production settings – writing about processes and procedures. Alertly maintained processes won’t wait for video depictions to keep them current. But a useful guideline always remains – there’s no substitute for clear, cogent presentation, whether “animated” or not.

So be ever mindful of your writing and drafting skills and keep polishing them – static words and diagrams remain with us, and always will, even as recorded images flit by. You can’t underline a video, after all. (Or can you?) – Doug Bedell

Technical Writers Need to Be Communicators First

Posted on June 23, 2016
Filed Under Communication | Leave a Comment

Craig Haiss has poured 15+ years of technical writing into a highly experienced post on his HelpScribe blog. Other writers, whether as experienced or not, will likely appreciate Craig’s reflections on the road he’s travelled.

He’s grouped and highlighted his past production into such categories as “User manuals,”Training guides” and “White papers.” The references aren’t necessarily to actual documents but how to produce them, under such headings as “Know your audience” and “Know what distinguishes you from your competition.”

Competition? Most likely. “Chances are,” Craig advises, “your sales pitch won’t be the first to come across the desk of your potential client. So, why should you get the sale?”

The advice that follows is designed to highlight your professionalism. Understand what that involves, at least as a refresher from a highly experienced colleague. Craig provides input on everything from White Papers to Disaster Recovery Plans and Communication Plans.

What does a technical writer need a Communication Plan for? Plenty, if he or she wants to make a profitable imprint on the field. “Gather existing notes on communication policies,” Craig urges. “Often these will be organized and distributed in an inconsistent manner. Writing a communication plan gives you a chance to consolidate them and make the easily accessible.”

Yes, organizational communication is too often circuitous, casually attempted and, therefore, not as successful as it ought to be. Rather than expect you to read on here,
we direct you to Craig Haiss’ resourceful post. Before a technical writer functions as a writer, he or she needs to be an effective organizational communicator. That’s where clients and assignments hail from.

Remember: Communicating isn’t necessarily the same as writing. It creates an effective environment for writing. First one, then the other.– Doug Bedell

Putting It All Together

Posted on June 16, 2016
Filed Under Uncategorized | Leave a Comment

Interana Inc. is a behavior analytics company in Redwood City, CA., an organization in which Neal Kaplan is the Senior User Assistance Manager. Kaplan has 20+ years experience as a technical writer and distilled his experience into a presentation at the recent Write the Docs conference in Portland, Oregon.

Kaplan was concerned with relationships between the documentation and customer support units of organizations, “Two Great Teams that Work Great Together,” or need to, to be sure. He’s posted his slides on the Web and they’re well worth experiencing, as though you were at the meeting.

The people who write manuals and other support materials have to be working in concert with their colleagues who provide direct support to an organization’s customers. That’s a truism that needs to be achieved in daily practice. “We don’t want customers to shut up and go away,” one of Kaplan’s slides reads. “Happy customers = more dollars” the next one notes.

What occurs when the two presumably collegial units aren’t in synch? “Frustration” proclaims Slide No. 31. There follow a number of steps Kaplan recommends to insure that the two groups are indeed working together toward a common aim.

“Knock down silos” is prime among them. Insure that the document writers and the document interpreters are working together for clarity and mutual understanding, relationships that can then be shared with customers, to everyone’s gain.

Kaplan delivered his message to 400 attendees at the Portland conference and is now sharing it with many thousands more on the Web. It’s a message that never wears thin: Technical writers have had to accomplish much in terms of training and experience to get where they are. But all that effort is of little use to anyone if it’s not shared with empathy and clarity with colleagues in other departments and their hoped-for customers in the wider world.

Super-evident? Probably. Readily practiced? Not always. Absorb Neal Kaplan’s slides. – Doug Bedell

Succeeding With Patient Chops

Posted on June 14, 2016
Filed Under Communication, Technology | Leave a Comment

In any field worth succeeding in, success doesn’t come easily, including technical writing. You need, first, to be effective and, then, be appreciated for being effective. But to demonstrate effectiveness, you need a sure-enough challenging setting in which to demonstrate accomplishment. And you don’t find such a setting easily. It’s sort of a circular process.

So here’s a lead on a couple of sites to provide encouragement: Heroic Technical Writing’s post on “Failure Resumes” and the Harvard Business Review article that prompted the post in the first place.

The Harvard piece introduces us to Johannes Haushofer, who graduated from Oxford with honors and has two PhDs, in economics and neurobiology. But he recently posted on Twitter a “Curriculum Vitae of Failures” to “balance the record” and “encourage others to keep trying in the face of disappointment.” (Dr. Haushofer is now an assistant professor of psychology and public affairs at Princeton University.)

The linked post contained “lists of Degree programs I did not get into, Research funding I did not get and Paper rejections from academic journals. It also includes Academic positions and fellowships I did not get and Awards and scholarships I did not get…”

“Most of what I try fails,” Dr. Haushofer summed up, “but these failures are often invisible, while the successes are visible. I have noticed that this sometimes gives others the impression that most things work out for me.

“As a result, they are more likely to attribute their own failures to themselves, rather than the fact that the world is stochastic, applications are crapshoots, and selection committees and referees have bad days.”

(“Stochastic,” by the way, means “Of, denoting, or characterized by conjecture, conjectural,” or “to infer from inconclusive evidence; to guess,” according to my American Heritage Dictionary.)

So hang in there. It’s a big, wide, wonderful world becoming ever more complex, with correspondingly more opportunity for those who function with clarity, verve and patience, including, not least, technical writers. – Doug Bedell

Clarity Counts for Everyone

Posted on June 3, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

What’s a technical writer’s purpose?

Sarah Maddox on her blog Ffeathers gives that timeless question (at least since the first technical document wafted through a transom) a fresh spin by quoting Joao Fernandes, whom she heard speak at a conference:

“Help build products that need no documentation.”

Yes, Sarah notes, “Our users don’t want to read the docs. They want to use the product.”

Accordingly, technical writers should be on both the design and delivery ends of projects and equipment. If you’re not, ask why not.

A technical writer, Joao is further quoted, should be the “CEO of the docs.” How’s that for a sense of purpose? Without clear documentation, an organization can’t function. So you’re virtually in control of your organization. And your CEO will appreciate it if you function clearly and concisely. (He or she may need some help with that, too.)

The best documentation, Fernandes added at the Docs NA 2016 conference, may be “very little.” Strong organizations begin with clarity in designing their own mission and goals before serving users.

You’ve known it right along: Technical writing is, or should be, a highly strategic function. Act on that recognition every chance you get, clearly and deliberately. Hopefully, you’ll be thanked for it. – Doug Bedell

Don’t Fret Over Procedures That Flit By

Technical Writers Need to Be Communicators First

Putting It All Together

Succeeding With Patient Chops

Clarity Counts for Everyone

Recently

Categories

Archives

Blogroll

Find It