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 Writing’s Lineage – Surely It’s Deeper than Digital

Posted on January 10, 2017
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Think technical writing just appeared, that it’s arisen out of contemporary necessity, without a pedigree of its own? Not so – technical writing, says Monalisa Sen and Debarshi Gupta Biswas on tcworld has a lineage of its own. But they only date technical writing from the “first technical publication” in 1949.

We’d think the craft would go back farther than that – what did it take, after all, to understand how the Monitor and Merrimack, or even a Roman chariot, worked in their own times? Yet Monalisa and Debarshi start with the “First Technical Publication” in 1949. “Joseph Chapline,” their posted chart explains, “wrote a user’s manual for the BINAC computer that he developed. This was groundbreaking, considering the need for technical communicators was not established…”

Oh, we see. Sen and Gupta are dating technical writing from the advent of computers. That, however, strikes us as rather restrictive, assigning the craft as our own birthright rather than an explanatory discipline going way back. We prefer the latter–instructive materials are part of humanity’s broader heritage.

Maybe technical writers weren’t called technical writers much before the Digital Age. But we’d like to see that discussed a bit. Anything that had supportive qualities in a world of everyday mercantile or military value has had to be validated as reliably dependable, hasn’t it?

It strikes us that this question of the ancestry of technical writing, the craft’s applied heritage, could do with more discussion. If you’re so moved, contribute to the record in a comment here. Many thanks! – Doug Bedell

Digital or Not, Be Clear

Posted on November 28, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Face it, modern technical writing can sometimes get you involved with software, either by reading about it or using it anew. Technical writers didn’t used to be concerned about a digital dimension – getting words, processes and procedures down in sufficient clarity was enough.

Yet Sarah Maddox on Ffeathers offers solace amidst change in discussing a short book by Andrew Etter – 11,000 words in a 45-minute read – Modern Technical Writing: An Introduction to Software Documentation.

“Every now and then,” Sarah notes, “I’ve heard people say we shouldn’t focus so much on the tools when discussing our profession and how best to perform our role. I’ve thought that too, at times. But it seems to me that these two aspects of our work are becoming more and more interdependent. The tools make a specific way of working possible, and the way we think of our work determines the tools we choose.”

So, even if you’re merely interested in contributing a knowledgeable tweet to Twitter, you’re engaged in a form of digital reality. It’s creeping up on us. It may well be where you catch the attention of colleagues in their daily rounds, maybe even at a coffee shop. If you become known as having something authoritative to say, you’ll be found.

Whatever you’re writing about, the most important aspect of the task is to be well-informed and other-focused. Especially in technical writing, you need to be accurate and understood.

If you’re writing at book length, as Andrew Etter was, you may even find yourself, as Sarah imagines, on Amazon near Strunk and White’s classic Elements of Style. And that would be, as more and more of us might say, awesome.

In their own ways, Sarah and Andrew get into many of the aspects of modern technical writing. But wherever the final product may appear, the basic needs – whether in digital or paper settings – are accuracy and clarity. That’s always been the case.

Increasingly, what’s being added is empathy – meeting a reader or coworker where he or she is on a job or in some other learning environment. (Yes, maybe even tweeting at Starbucks.)

Sarah adds: “Andrew talked about old methodologies and tools versus the new ones…I’ve heard people say we shouldn’t focus so much on the tools when discussing our profession and how best to perform our role. I’ve thought that too, at times. But it seems to me that these two aspects of our work are becoming more and more interdependent…The details are in Andrew’s book.” It’s available, digitally, from Amazon. – Doug Bedell

Making Technical Writing Dance May Be Next

Posted on September 30, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

It’s not a very inviting page, nor an especially well-edited one. (“During few last years, the way how people consume information changed drastically…”) Yet “New trends in technical writing” on the Technical Writing blog does provide interesting projections of where the craft may be headed.

Downloaded copies of user manuals and brochures are becoming increasingly popular, instead of copies stored on shelves. “Storing big amounts of hard-copies is no more acceptable as home and office users tend to save space and avoid unnecessary stacks of documentation.” Not an especially elegant sentence, but an attempt to stress that digital storage of texts is something worth learning about.

Another cited trend is “simple animated 3D assembly animation…” If you’re not up on providing animated directions, that’s something to dig into.

“At IAM consultants, Ltd.,” notes the blog writer, “we use state-of-the-art software to keep (up) with the latest trend(s) of technical writing.” That’s followed by an offer to turn your papers and manuals into “interactive and media-rich presentations, so that your customers would be thrilled..”

The post isn’t dated, so we don’t know how far along this digitally based approach to technical writing has become. But you’ve been warned, or advised, let’s say, to start becoming familiar with what users might read on screens rather than pages, and then download what’s helpful to them – what’s really worth saving. We’re not just writers any long, we’re presenters as well. Documentary dancing may be next. – 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)

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

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

keep looking »

Technical Writing’s Lineage – Surely It’s Deeper than Digital

Digital or Not, Be Clear

Making Technical Writing Dance May Be Next

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

Technical Writing’s About Reality

Curiosity: A Reminder Of Ever-Present Opportunity

Don’t Fret Over Procedures That Flit By

Clarity Counts for Everyone

Present Guidance Via Graphics, Too

Musings On Coming to Work

Recently

Categories

Archives

Blogroll

Find It