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.

Slides for a Tech Writer’s Craft

Posted on December 16, 2016
Filed Under Business, Communication, Technology | Leave a Comment

Wow, what a resource Google is! You knew that already, but here’s absolute proof from a technical writer’s perspective: From 2006, 10 years ago, we’ve come across, via Google, a set of slides on “Sentence Structure of Technical Writing.”

The slides are by Nicole Kelley, who in 2006, anyway, was in the Program in Writing and Humanistic Studies @ MIT. They apparently were some of her lecture materials. And they lead off with a quote from George Gopen and Judith Swan from The Science of Scientific Writing:

“The fundamental purpose of scientific discourse is not the mere presentation of information and thought but rather its actual communication. It does not matter how pleased an author might be to have converted all the right data into sentences and paragraphs; it matters only whether a large majority of the reading audience accurately perceives what the author had in mind.”

Accurate perception, of course, is especially critical in technical writing. Enough said about that particular point.

Ms. Kelley’s Google-enshrined thoughts go on to discuss Planning/Rethinking, Writing and Revising, key components of a tech writer’s craft. “Planning” includes “Know your purpose, Know your material.” Don’t start writing and guidance materials until you’re clear on who you’re trying to communicate with. If it’s, say, a power plant, it’s most likely the entire workforce, whose members have differing backgrounds and needs – as doesn’t anybody when you think about it?

So clarity and avoiding jargon come next. And they lead to a host of other timely principles, with examples. What a great, Google-summoned resource! There are 24 slides in all, and they amount to a one-stop education in productive technical writing. Have at them! – Doug Bedell

When Proposals Don’t Click, Keep Making Them Anyway

Posted on November 11, 2016
Filed Under Business, Communication, Technology | Leave a Comment

We don’t want to be associated with the ilk of consultants who have their proposals rejected, but we all experience rejections. We’re not know-it-alls, at least that anybody much recognizes.

So Bart Leahy’s post on Heroic Technical Writing, “Dealing with Proposal Losing Streaks,” is taken kindly and appreciated.

“This past week,” Bart writes, “a proposal I helped a customer write won the bid. This was a moment of joy for the customer and a great relief to me. I’ve worked on a lot of proposals over the past 3-4 years. To the best of my recollection, I’ve lost nearly every single one, going back to 2012 – the last time I can recall a confirmed win.”

We’re not suggesting that a “losing streak” like that is normal or to be emulated. But rejections are probably more typical than acceptances for many of us. The important thing when they occur is to remain stout-hearted and ready to pick up and move on to the next hopeful tender.

Neither the U.S. nor world economies are organized around any of us. It’s a hurly-burly out there and we’re probably not known or appreciated to the extent we may feel we’re due. Even if we were, selling services is always a challenge – prospective clients have genuinely competing uses for their funds.

So, in the spirit of the Godfather, Bart advises that, “It’s not personal, it’s strictly business.”

Beyond ruing reality, though, there are steps to be taken to bolster the pertinence and timeliness of proposals. The first is to know prospective clients and their needs as appropriately as possible. “Appropriately” means in an applicable business context – not just their own wares, but what competitors are offering.

Timeliness and, yes, spelling and crisp writing count a lot. “People judge you based on the quality of your spelling.” Bart writes, “Those are the same people picking on you for typing in Twitter-speak.” Now there’s a term for our digital times – yet don’t be too hard on Twitter, it’s not proposing, it’s promoting, and that’s hugely important too.

There are several other helpful advisories in Bart’s post, but you can, and should, get them from there rather than here. The point we’re trying to make is, “Don’t be disheartened by rejection, it happens to the best of us.” Just keep on proposing.

Remember, as Bart Leahy advises, the Chicago Cubs manager who put it, “Anyone can have a bad century.” And try to add a little something more to your pitches. – Doug Bedell

We’re Leaders All, And Need to Think That Way

Posted on October 10, 2016
Filed Under Business, Communication | Leave a Comment

Technical writers are likely to picture themselves as contributing from “behind the scenes,” without much sense that they have a leadership role in the organization they’re serving. But principles of good leadership and professional awareness need to be on everyone’s mind these days, no matter how much of a leadership back-bencher we may fancy ourselves. We’re all filling big shoes.

Thus we find the Heroic Technical Writing blog musing on “Five Principles of Good Leadership,” an appropriate focus indeed. They are: A sense of mission, A sense of appreciation, An ability to inspire hard work, A willingness to respect employee expertise and A willingness to back up their team.

There’s also, of course, A sense of being trustworthy, of having integrity and keeping calm. We’d add that one.

Living up to all these attributes makes one, in fact, a leader too, no longer a backbencher. It may be quiet, unassertive leadership, but it’s way-showing nonetheless.

“Occasionally,” notes Bart Leahy, proprietor of Heroic Technical Writing, “I’ve encountered individuals who ask me to edit or rewrite their work and then, when I do, they push back– either against my specific wording or my advice on how to approach a particular communication challenge. This can be particularly vexing when the leader in question specifically confesses ignorance about a subject.

“Repeated often enough,” Leahy adds, “this behavior eventually creates reluctance to offer input or advice.”

That’s truly so. Technical writers may not be in the forefront of an organization, but the best ones are formative elements in an organization nonetheless. They know creative from crass, and demonstrate the crucial difference by being true to their craft and the best interests of the organization they’re serving. Trust will ultimately be lost, but it won’t be trust in the technical writer (if he sticks around long enough).

A good organization is a set of worthy aspirations maintained under pressure. Technical writers serving such an organization can sense its heading perhaps before the executive helmsman. Tech writers aren’t just drafting procedures, they’re taking the best aim they know on an organization’s proficiency and continued success.

“All of these behaviors engender a sense of trust,” Leahy notes in closing. “If a leader loses their team’s trust, they can also expect to lose all the rest of the attributes described above. But given an environment of vision, sincere appreciation, shared work, mutual respect, and trust, leaders can create high-performing teams who will want to work with that leader again and again.”

And their technical writers can tell them as well as anyone how they’re doing. – Doug Bedell

Virtual Reality at Elevator Doors? – Indeed So

Posted on September 19, 2016
Filed Under Business, Technology | Leave a Comment

Looking through a lens into the future no longer requires waiting for the future. Increasingly the future is now. Take, for example, maintaining an elevator.

Maintaining an elevator? Right. Thyssenkrupp is equipping its 24,000 technicians with virtual reality headsets – Microsoft HoloLens with Skype – so that they can reach back to their offices, or wherever they need to go, for help in doing their jobs. Right in front of them is a colleague or blueprint, or whatever may be needed to help with the task the technician is dealing with.

This is astounding, and very soon, we suspect, will be in the “must have” category for technical people in many realms.

Explains the Cherryleaf Blog, “HoloLens with Skype capabilities enables over 24,000 Thyssenkrupp technicians to receive remote assistance by subject matter experts who can provide visual and audible advice using HoloLens’s mixed reality capabilities. These remote subject matter experts can see what onsite technicians see in real time and even draw visual indicators on the technician’s field of view to assist with repairs. By adding HoloLens to their solution, Thyssenkrupp has set a new standard in elevator innovation, reducing the average length of its service calls by up to four times.”

Wherever the idea for virtual reality maintenance originated – maybe it was playing with computer games – it’s now becoming a real world, on-the-job capacity. And it’s saving Thyssenkrupp elevator technicians lots of time as well insuring that they’re making the right moves.

Ellis Pratt at Cherryleaf, a digital technical writing colleague, has provided this information and insight into an emerging process reality that’s both fascinating and reassuring in the context of technical innovation. Reassuring? Yes, you might say, elevators will shortly be having more ups then downtime. – Doug Bedell

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)

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

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

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

Clarity In Progress

Posted on January 31, 2016
Filed Under Business, Communication, Technology, The Writing Life | Leave a Comment

Who would disagree that the biggest issue in technical writing “is the inability to see simplicity in complexity.” If you’re trying to reach even a veteran engineer with guidance or instructions on a new procedure or process, you want to be as direct as the process allows.

We thank Mark Crawford on the ASME.org site for discussing this question of simplicity in complexity via his “How Engineers Can Improve Technical Writing” post. It’s been out there a few years now but, as we suspect may be true of other colleagues, we’ve just caught up with it in the Internet’s vastness.

To write with clarity and directness requires that you understand a technical situation as fully as your capacities allow. We assume you wouldn’t be writing about such challenging material if you weren’t qualified to do so. The issue isn’t technical competence so much as communication prowess. You need to describe a process clearly and competently. When you think you’ve finished, the test is, Have you communicated well?

“After all,” Crawford adds, “technical writing is not just about language skills – it’s about how we think.” Indeed. Clear writing requires clear thinking. And that’s as much a communication issue as a technical one. You can’t communicate well if your thinking is garbled at the gate.

So before plunging into a process, take time to review it first. What is it intended to accomplish? How can a reader/user get there promptly, clearly and safely? Simple sounding, yes, but not so simple in practice. Often we’re too rushed, or feel so, to
organize, settle down and produce a clearly described series of steps to get there as intended. – Doug Bedell

keep looking »

Slides for a Tech Writer’s Craft

When Proposals Don’t Click, Keep Making Them Anyway

We’re Leaders All, And Need to Think That Way

Virtual Reality at Elevator Doors? – Indeed So

Technical Writing’s About Reality

Don’t Fret Over Procedures That Flit By

Musings On Coming to Work

Virtual Reality An Opportunity For Well-Heeled Technical Writers

Economics Without Weeds

Clarity In Progress

Recently

Categories

Archives

Blogroll

Find It