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 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

Comments

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

Comments

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

Comments

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

Comments

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

Comments

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

Comments

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

Comments

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

Comments

Ready, Write, Aim – No, That’s Not It

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

What’s the most important element in starting a technical writing task? (Or any other, for that matter.) Why, it’s your aim, of course. “What am I trying to accomplish with this? Where are we headed?” Putting first things first requires that you have a good fix on what you’re aiming for before you start doing it.

Don’t be the kind of writer who just tries to fill space – that won’t have a worthwhile outcome. We used to do editorial writing, with a wide column of empty space to be filled daily. But filling that space wasn’t, or shouldn’t have been, our aim. Having something to say was what benefitted readers, sharpened their perceptions and expectations of us. That was, or should have been, our real aim.

Such thoughts occurred (again) while reading Neal Caplan’s post “…You’re Not Good Enough.” Being judged by other people’s standards is okay, so long as you all have the same aim. But if you don’t, watch out. You may get to where they’re headed and find, pretty quickly, that it’s not where you need to be. It’s all in your aim.

Taking careful aim shouldn’t be any different for technical writers than anyone else. What in the way of writing crisp, efficient documentation should be your intent on behalf of those who will be using it? Don’t just start spieling out directions. They may get pretty roundabout.

“As nice as it is to hold a copy of a book that you wrote,” Neal notes, “it’s not so nice to tell your customers that they MUST read that book before they can use your product. Or, more likely, that shelf full of books. This is the opposite of ‘just in time’ help: it’s ‘become an expert on this product before you ever think about touching the UI.’”

Your aim isn’t to help colleagues become expert at what you’re doing, but to become better at what they’re trying to accomplish. There’s always more to discover, learn and know. The real question is: to what end? What are you aiming for, organizationally and individually? Keep focused on that; it’s what matters most. – Doug Bedell

Comments

Economics Without Weeds

Posted on March 29, 2016
Filed Under Business, Technology | Leave a Comment

We’re penning this commentary on a post by Jim Grey (on his Stories from the Software Salt Mines blog) not only because we like the graphic (left) that runs with it, but because it gives the lie to the notion that economics are nearly everything in business. Creativity, focus and flow count for a lot too.

Jim’s noting, and complaining, that Silicon Valley tech companies appear to be moving their tech support departments to middle America because they can pay support techs less there. Let the support folks answer phone queries from the boondocks, rather than the coasts, is what it amounts to. Yet that’s a profoundly mistaken view if a company’s more creative people are on the coasts. If creatives aren’t housed with the support people, we’d counsel, watch out!

Over time, a tech company might well be denying itself insights that could make it’s products better and more customer-focused, because they’re not being made in a system in which front-line customer/technical feedback is being readily heard. A system implies activity centers in a configuration that readily and productively support each other.

“Support,” Jim Grey writes, “really can be a good place to grow talent for other teams because techs know the products and, more importantly, how users actually work with and experience them.”

Who’d a thunk? That’s what happens when support people spend all the time they typically do with confused and possibly disgruntled users. Why deny a firm’s “creative” people the insights they garner or have them coming in secondhand, from the heartland to the coast?

Stupid, stupid. “Here in the Midwest, where cost of living is generally low,” Jim observes, “the startup, small, and medium-sized companies where I’ve worked don’t outsource customer service. Those workers are already plentiful and inexpensive. And so support is always down the hall or on the next floor. Developers and testers become friends with many of the support techs.”

So why doesn’t Silicon Valley see the benefit in having everybody together, too? Can it be economics alone – if so, it’s a false sense of economics. Or is there something of a caste system at work as well – “creatives” and everybody else. If so, and again, that’s simply stupid.

Take down the “Road Ends” sign in the photo and yank out those weeds. We’re all in this together, designers and enablers alike. That’s the best kind of economics. Amen. – Doug Bedell

Technical Writers Need to Be Communicators First

Comments

Putting It All Together

Comments

Succeeding With Patient Chops

Comments

Clarity Counts for Everyone

Comments

Present Guidance Via Graphics, Too

Comments

Musings On Coming to Work

Comments

Virtual Reality An Opportunity For Well-Heeled Technical Writers

Comments

An Awesome Web Community

Comments

Ready, Write, Aim – No, That’s Not It

Comments

Economics Without Weeds

Comments

Recently

Categories

Archives

Blogroll

Find It