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

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

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

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

Musings On Coming to Work

Posted on April 29, 2016
Filed Under Business, Communication, The Writing Life | Leave a Comment

Who are you? Even though you’re a technical writer, the question matters greatly. Technical writing isn’t supposed to be about psychology. It’s more typically about getting from here to there, providing directions, if you will.

Yet we all function in context and an essential part of that context is ourselves. We bring to work a history and collection of abilities and experiences that enabled, and keep enabling, us to succeed in the first place.

So before numbering steps, editing formulas or getting operational about a piece of equipment, remember that a given process starts with us and where we’ve been until now. What are we bringing to the scene that somebody else saw in us, or at least hoped they did, when they hired or assigned us?

What’s our state of readiness for the next move? We shouldn’t just plunge in, but be aware of alternative moves, some of which might be better, and some worse, but all potentially emanating from us, to an employer’s or client’s advantage.

Obvious thoughts? Probably. But how often do we expressly have them? Wouldn’t they be helpful as recurring prompters? Such meanderings have been stirred by a post on Bart D. Leahy’s blog, “Heroic Technical Writing”.

“My personal marketing advantage, for example,” Bart writes, “is Trust, which includes things like showing up on time, getting good work done on time, and being someone who takes the time to learn his clients’ work and priorities so that I write a better product.” How many of us actually do this last? How much do we actually know about a client’s needs and promptings before start serving them?

Inner precedes outer. Before we put words on a screen or paper, we need to be clear about where they’re coming from. Not just a setting, but the previously arrayed elements of that setting, including those internal to the people who created it.

We could get carried away at this point and start arguing that everything began with Adam and Eve. But no, an assignment begins with what’s gone into a particular setting, the setting in which we’re treading either with aplomb or caution.

Bart Leahy prompts these thoughts with his review of a book, “Fascinate: How to Make Your Brand Impossible to Resist.” For us as individuals the question becomes, “How do we make ourselves impossible to misunderstand or be misunderstood?” No small promptings, these. We need to be continually mindful of them. We need to be trustworthy.

We’re not just coming to work, but working in a given direction. Ours or our client’s? It needs to be the client’s, of course. – 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

An Awesome Web Community

Posted on April 20, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

We need to tip our hat, or maybe more, to Technical Writing World, the “social network for technical communicators.” Yes, more – so we’ll blog a bit about the site. Why? Because it’s got over 2,800 members, and that’s great for a social network that’s not Facebook or Twitter.

What’s all this gushing about? Well, we’re halfway through our second reading of Mark Schaefer’s latest book, “The Content Code,” which describes in detail how hard it is to get discovered on the Web these days, and how it’s getting even harder.

What Technical Writing World’s impressive membership indicates is that technical writers are discovering each other in a world-wide community of engaged, conscientious people. We knew they were conscientious, of course, but to join and sustain a worldwide community like TWW is exemplary these days.

For the Web is like a vast sea that’s getting ever wider and deeper, one where it’s increasingly hard to be found and engage with other colleagues. We look at Technical Writing World and all sorts of sharing seems to be occurring there. There are 189 blog posts, 607 forum discussions, an upcoming event next month of the Society for Technical Communication, leaderboards to promote the most active members and their contributions, a Techcomm Superfeed with the latest blog posts from members, and postings of technical writing jobs. (Might this be a special reason for the site’s popularity?)

“I’ve spent the last year studying this essential concept of content ignition, Mark Schaefer writes in ‘The Content Code,’ and it has changed me. There is a science and psychology behind the act of sharing content that is awe-inspiring and beautiful and mesmerizing. People share content for hundreds of reasons, but there is a uniform process behind it inexorably linked to self-image, caring for others, and even compassion for an author or brand.”

Well, nobody seems in need of compassion on “Technical Writing World,” but it is indeed an awe-inspiring site, a testimony to the communal challenge, satisfaction and sharing behind technical writing taken seriously and collegially. – Doug Bedell

« go back — keep looking »

Storyboards for Technicians

Technical Writing Defined as a Challenging Task

Curiosity: A Reminder Of Ever-Present Opportunity

Technical Writers Need to Be Communicators First

Succeeding With Patient Chops

Clarity Counts for Everyone

Present Guidance Via Graphics, Too

Musings On Coming to Work

Virtual Reality An Opportunity For Well-Heeled Technical Writers

An Awesome Web Community

Recently

Categories

Archives

Blogroll

Find It