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.

Presentations With Forethought

Posted on January 16, 2017
Filed Under Communication | Leave a Comment


Here’s Sarah Maddox, a demonstrably savvy technical writer, describing how she prepared a presentation for an upcoming summit of the Society for Technical Communication. The process, she notes, starts with “grabbing an idea when it floats by.” Indeed.

How many of us on our daily rounds are struck with an idea worth pursuing but don’t jot it down, only to have it get lost in a stream of mental activity? Value such ideas, carry a pocket note pad, and write them down when they occur. Cursory as it may seem, that’s an invaluable technical discipline. An idea recorded is an idea in play.

Then, Sarah advises, seek out speaking opportunities to share your ideas. That not only furthers a collegial dialogue but spreads awareness of your skills and competence. Preparing an outline is an essential step here. You don’t simply have an idea, you begin to flesh it out. And you’re after clarity, not a tangle.

Then write a summary of what you’ve begun to create. Once accepted for a program, it can be used as a “blurb” for what you intend to present. Sarah has lots of ideas for building your presentation, including taking a walk, in the woods or wherever you prefer to amble. “I don’t consciously think about the problem,” she explains, “but I’m open to suggestions from my subconscious.” When one or more arrive, she sends herself an email “or scribble a note on a scrap of paper.” The point is to preserve a promising insight.

Ideas can rapidly grow complex – get those initial promptings down.

Sarah’s got more suggestions, including a tip on avoiding stage fright. The best way we know to do that, though, is to be well prepared, to step up to a podium confident that you have something worthwhile to say and are sharing it enthusiastically. The likely audience reaction? Hey, this speaker may be worth heeding!

The last thing you want to do in a technical presentation, which is risky enough, is avoid giving an audience the feeling you’re imposing on them. Teaching of any complexity can be done well if it’s presented clearly and enthusiastically.– Doug Bedell

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

At the Holidays, Twitting Amazon

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

Oh, the power of a good technical writer, or so it appeared. But hold on! Here’s a post on the Darth Continent blog on a “Starry Sky holiday light projector” that’s still available at Amazon.com, despite disappointing a technical-writer customer and prompting him to blog about it.

The projector was supposed to “spray” red and green lights on the writer’s home. “I purchased one of these through Amazon, and it didn’t take long at all to see why this particular product is no longer available,” or so the unfortunate technical guy thought. “Just one night after setting it up in my front yard, the green light disappeared, leaving just the red. Picking it up and shaking it gently yielded a disconcerting rattling inside.”

He disassembled the item, as any tech guy would likely do, and figured out how to fix it. But his parting rueful comment is: “Review products carefully and pick one that does what you want it to do but isn’t rife with poor quality control as demonstrated here.”

Unfortunately, a technical writer needs to know his source place, not just patronize it, to insure that he’s getting the results he expects. And (apart from Amazon and it’s mail-order business) it’s a tech writer’s job to prompt that sort of continually bright, end-result process. – Doug Bedell

Successful Cookie Baking – From Mom, an Acknowledged Expert

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

How is technical writing like cookie baking? Bart Leahy raises this holiday-time question on his Heroic Technical Writing blog not so much in the interest of better cookies, but in reprising an oft-proven process for exemplary technical writing.

First, be sure you’ve consulted the experts in whatever process you’re recording. In Bart’s case, after he’d botched a couple of batches of cookies, they were his sister Colleen and, then, the source of the cookies he’d remembered so fondly, his mother.

When Bart’s Mom asked about the results he was getting, he replied, “Well, the cookies aren’t very sweet and (they’re) a bit flour-y tasting. Maybe a little salty.” He described the procedure he was using to get so unsatisfactory a result. After his Mom asked a few clarifying questions (“We walked through my procedures…”), Bart got his answer – he wasn’t using enough sugar and salt wasn’t included in his Mother’s recipe.

Yet Bart’s recipe had them both listed in the quantities he’d used. Clearly, it was mistaken. Bart had gone to an acknowledged expert, asked some clarifying questions and corrected a couple of details he’d gotten wrong.

And so, we’ve reached the core of the technical writing process: Consultation with experts and diligence in recording accurately what’s been learned. It can then be confidently applied by it’s intended users (but none too confidently, until confirmed in a few early trials).

When a technical writer gets to feeling expert himself or herself, that can be dangerous. A process doesn’t originate in the writer’s mind or keyboard, but in those who used it beforehand and smoothed it out for reliability on the scene. Being a good technical writer, as we’ve noted before, is much the same as being a good reporter. Or a good cookie baker, once you’ve gone back to the source of what you’ve been seeking to reproduce. – Doug Bedell

(Illustration: MidwestLiving.com)

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

Digital or Not, Be Clear

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

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

When Proposals Don’t Click, Keep Making Them Anyway

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

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

1210-1241070280vbda
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

Making Technical Writing Dance May Be Next

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

robot-1169742It’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

Cruising Clearly Through a Product or Process

Posted on September 8, 2016
Filed Under Communication, Technology, Uncategorized | Leave a Comment

images-1
Web users are becoming increasingly savvy about getting the most insight possible into products they’re considering buying and using. So clearly presented documentation, notes the easyDITA blog, is doubling in importance: As a guide to value as well as use.

“So, start thinking about documentation as a marketing and sales resource,” easyDITA urges, “Don’t hide it behind logins or limit access to actual customers. Feature links to it on your product pages and reference it in your marketing materials.”

Brilliant, providing the documentation is clearly and usefully prepared. Not that instructions for putting equipment to work need to read like a novel. But they should read like a purposely prepared, easy-to-use guide that you’re proud of.

“Work with your tech writers to develop a clear tone and voice, and conversational language style guides that won’t scare away a first time visitor doing their homework. Generally speaking, this change in tone from very technical to more plain language style has become the standard for technical writing.”

Gee! Technical writing that breezes right along providing obvious value! How about that!

“In the world of content management, easyDITA notes, “documentation teams have often been relegated to a poor relations role in many companies, resulting in understaffing, limited budgets, and backlogs of inaccurate or out-dated documentation.” How dumb, once it’s pointed out, often too late.

“Finally, give the docs team credit where credit is due – they should be direct contributors to the bottom line, not a cost center.” It’s amazing how useful work springs into prominence once actual value is pointed out! – Doug Bedell

keep looking »
Email Subscribe

Recently


Categories


Archives


Blogroll