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.

Storyboards for Technicians

Posted on August 26, 2016
Filed Under Communication, Technology | Leave a Comment

Pictures can “tell a thousand words,” or at least a snapshot’s worth. Why not consider including them as part of a written technical procedure or manual? Greg Larson on the TechWhirl blog provides inspiration for doing just that.

Greg suggests both pictures and sounds. But to keep the result from becoming a confusing garble, he advises planning it carefully in advance – how else but with storyboards? “Storyboards,” he writes, help you organize before you begin to develop your presentation, video tutorial, animation, simulation or web-based training, by putting it into a format that allows others to see the sequence of your presentation before you begin production.

“It helps organize the pile (or the idea that could become a pile) of videos, photos, audio clips, and documents according to a logical sequence that can be aligned with text or audio.”

You might not be planning that ambitious an audio-visual presentation, but laying out pages in advance, what newspaper and magazine editors have always done, will insure a more coherent, informative result. Technical writing, illustrated or not, always has to lead to a safe, effective endpoint. We’d say “conclusion,” but this, after all, involves procedures, not novels. And procedures can bring primal results.

For technicians, being resourceful never includes being casual. A display of photos in a procedure or manual has to be appropriate to the end result – carefully chosen, thought through and illustrative of the process involved. No comics allowed!

“Storyboards,” Larson explains, “help you organize before you begin to develop your presentation, video tutorial, animation, simulation or web-based training, by putting it into a format that allows others to see the sequence of your presentation before you begin production. It helps organize the pile (or the idea that could become a pile) of videos, photos, audio clips, and documents according to a logical sequence that can be aligned with text or audio.”

So pile it on, friends, but carefully. – Doug Bedell

Writing Clearly About Documentation Can Be Done – Of Course It Can

Posted on August 17, 2016
Filed Under Technology, The Writing Life | Leave a Comment

“Give every person his or her due” – a prime precept, if there ever was one. Why are we noting it here? Because Neal Kaplan on the Customers and Content blog warns about a couple of dangerous myths, a caution we second – that “programmers can’t write and writers can’t code.”

That’s pigeon-holing people when we should be thinking of eagles flying high. In this new digital age, people need to be recognizing complementary skills and developing them to the best of their abilities – human abilities, which can span categories.

Citing an article that got under his skin, “Why Developers Write Horrible Documentation,” Kaplan faults its writer for thinking in terms of generalizations, a hazard to be sure.

The particulars of the matter come down to what a given technical writer accomplishes both in terms of programming and explaining it well. It can be done. And it needs to be done more and more often.

Supposedly, developers get too close to a product. Well, did Herman Melville get too close to whales in producing Moby Dick? Of course not.

Developers can create a usable product, but they can’t be trusted to write the documentation? “Here’s the thing,” Kaplan explains. “maybe no one taught the developers about product docs, about what works and what does(n’t), about what their users are looking for.”

But they can learn – as Kaplan explains, he himself did. Complexity requires insight to get on better terms with understanding. Learning, rather than harpooning.

Lest we be accused of mixing eagles with whales, we’d best make the clear point that what comes out of a workplace is forecast by how relational and cooperative its denizens are.

Tasks clearly understood are likely to be tasks performed well. That’s a principle for technical writers and their colleagues to honor. – Doug Bedell
(Photo via Pinterest)

Technical Writing’s About Reality

Posted on August 10, 2016
Filed Under Business, Technology, The Writing Life | Leave a Comment

So what’s the most important trait of a technical writer?

Sharon Burton answers, no surprise here, that “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…?'” If you consider a technical writer to be an investigator, not merely a writer, as you should, the capacity to inquire and discover is his or her paramount skill. After all, the procedures produced have to be on-the-mark in a highly utilitarian way.

A technical writer has to be sure that he or she is describing reality as it exists and curiosity is necessary to insure that reality has been captured accurately, safely and unfailingly in words for others to follow. Technical writing is good, faithful guidance.

“Non-curious means you just want to format information other people give you,” Sharon Burton writes. And that’s not going to help anyone, least of all your users.”

So be sure you accept that technical writers produce ever-reliable information for path-finding, hard information about step-by-step reality. That’s it, folks. – Doug Bedell
(Image – TechWhirl.com)

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

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

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

Present Guidance Via Graphics, Too

Posted on May 6, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Up till now, Insights has been devoted essentially to technical writing, but it’s time for discussion of graphic aspects of the trade too. That’s thanks to Bart D. Leahy who, on his Heroic Technical Writing blog, discusses adding pictures to technical output – well, charts and graphs at least. They’re pretty heroic in their own way.

“Which graphic should you use?” is the post’s title, for you’ve got choices – between line, bar and pie charts and tables, to get things started. (You can also use photographs or drawings but we’re in the chart mode for now.)

Line charts, Bart Leahy advises, are good for tracking a single value or two over time and are helpful in showing trends. Bar charts can compare a host of items in terms of quantities, rather than time. Pie charts display percentage slices of a whole. And tables, while not so graphic, can compare text- and number-based information.

But watch out, unless you’re purposely trying to mislead, which, of course, you shouldn’t be doing. The way graphics are displayed, Leahy shows, can be misleading and you don’t want to be that crafty.

“Graphics are becoming increasingly important to how technical information is conveyed,” Leahy summarizes. “It is vital that technical communicators of all varieties understand the conventions, pros, and cons of of different visual representations… Take the time to present your data well and your readers will appreciate it.”

Well, it’s true that a picture can be worth a thousand words. But we’re not giving up on words – that can’t be done in the technical sector any more than anywhere else. But being mindful that graphics can offer summary views of material can help to enliven your text, which is something you should always be seeking, legitimately, to do. – Doug Bedell

Virtual Reality An Opportunity For Well-Heeled Technical Writers

Posted on April 25, 2016
Filed Under Business, Communication, Education, Technology | Leave a Comment

Here’s a fascinating example of where technology is taking us – using virtual reality viewers to simulate whatever setting we care to experience and learn from. The thought occurred that this immersive technique might possibly be useful (and certainly engaging) to technical writers with a visionary bent.

For example, the U.S. Navy at Pearl Harbor is using virtual reality at actual shipboard gun emplacements to detect and ward off simulated attackers. And there’s a paper available (by five writers) on “Teaching Technical Writing Using 3D Virtual Reality Technology.” We haven’t read it yet, and virtual reality gear may be expensive to acquire and use. But when you’re on a frontier, it’s good to be aware of the possibilities. The future, as we know, has a way of advancing rapidly.

Suppose you work on a large site with lots of gear to monitor and use to its full operational advantage. With a virtual reality setup you could possibly simulate contexts of interest without leaving your desk. That could allow a highly efficient use of your creative energy. Of course, there’d be costs, possibly substantial ones, to get you to that point.

Or maybe you’d like to experience a setting that doesn’t yet exist. We don’t know what’s involved in programming virtual reality, but it’s likely that this scenario is already being experienced somewhere. “Here’s where we’re headed,” a VR practitioner is saying, “and no, we really don’t want to go there. Here’s why.” All without leaving your morning coffee.

The potential for teaching technical writing in a classroom setting using virtual reality is explored in the paper referenced above, whose writers are interested in providing “practical learning environments for students.” And Google can likely direct you to other pathbreaking instructional material on VR.

The point is, virtual reality is a new technique for exploration and learning. Freshness tends to become ever more intricate, so we’d suggest considering VR while it’s still an opening book for technical writers. – Doug Bedell

« go back — keep looking »

Storyboards for Technicians

Writing Clearly About Documentation Can Be Done – Of Course It Can

Technical Writing’s About Reality

Technical Writing Defined as a Challenging Task

Curiosity: A Reminder Of Ever-Present Opportunity

Don’t Fret Over Procedures That Flit By

Succeeding With Patient Chops

Clarity Counts for Everyone

Present Guidance Via Graphics, Too

Virtual Reality An Opportunity For Well-Heeled Technical Writers

Recently

Categories

Archives

Blogroll

Find It