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

Comments

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

Comments

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

Comments

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)

Comments

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

Comments

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

Comments

Being Watchful About Digital Designs…

Posted on November 17, 2016
Filed Under Technology | 1 Comment

imagesYou can’t be too careful, it’s always been said in responsible technical circles. True, and the circles keep being enlarged in these digital times. Take, for example, the “construction” via a 3D printer of propellers for drones.

In a post on New Atlas, David Szondy conjures up the vision of an F-35 fighter plane on a routine supersonic flight. It kicks in its afterburners and “Suddenly, there’s an almighty bang as one of the turbine blades in the jet engine disintegrates and within seconds the US$85 million plane is tearing itself to pieces.”

Is it, Szondy asks rhetorically, an accident or sabotage? Well, according to researchers at Ben Gurion University (BGU), “this scenario could be an example of a new type of cyber warfare where saboteurs can fool 3D printers into creating self-destructing parts that are indistinguishable from the real thing.”

Szondy’s post describes how an email file sent to a simulated victim could launch a
a digital chain of events leading to a design failure and disaster. Read the post to get a sense of what could become wantonly possible in these hacker-beset times. And, if you’re in sensitive work, be ever alert to see that it doesn’t.

Computers provide bushels of information with such ease that we can brush aside considerations of its authenticity – not if we’re being professional, but if we’re digitally fatigued. The mere idea that we are turning design over to 3D anythings is losing its novelty. But a 3D printer’s instructions are merely digital files that can be manipulated on a laptop. Which can be subject to hacking. And thus, a chain of concern…

An international team of researchers from Ben Gurion University, the University of South Alabama and Singapore University makes all this clear in a paper they’ve done on “spoofing” 3D printers. It’s a tract for our times if there ever was one and Szondy provides a link to it.

(The photo above shows two seemingly identical propellers created on a 3D printer – but only one is authentic, the other is designed to destruct in flight.) – Doug Bedell

Comments

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

Comments

Like a Good Gardener, Help an Enterprise Keep Itself Current

Posted on October 18, 2016
Filed Under Uncategorized | Leave a Comment

25654050293_a6ac9c67a9_cHere’s a great analogy for technical writers from the “Stories From the Software Salt Mines” blog. Sure, you can keep adding features (in the form of text and photos) to whatever technical content you’ve been developing for months, or years.

But if you haven’t been conscious of keeping it all fresh and organized appropriately, if you’ve just been adding on…and on, watch out. Or if you’ve been describing an aging system as though it’s still new, that could be a double whammy.

“Software as a garden: to be able to grow more software, to be able to grow revenue with it,” the blog writer notes, “you have to keep the soil fertile and give the roots room. The problem is, gardening projects are a hard sell. These are things like refactoring older parts of the code that no longer serve efficiently, or upgrading or replacing outdated parts of the architecture, or redesigning subsystems that work fine today but can’t adapt to things the company wants to do in the future. When you tell executives you need to do these things, what they hear is that they can’t have new features while you do it. New features fuel growing companies.”

In short, you need to be observant, that is, current, as you write. If the setting you’ve been active in has been aging (and what settings haven’t?), have you kept it current in your own awareness and thoughts, and pointed out to its owners what you’ve been observing?

If you’re simply chronicling an aging, though originally awesome, system, watch out! If you don’t “tend your garden,” contribute to keeping it current, sooner or later it will stop producing. And nobody should be surprised at that.

Yet, notes the writer in the Software Salt Mines: “It was much the same story: the company had focused entirely on rapid new-feature delivery and not enough on ongoing design and architecture. After a decade, their soil had gone infertile and the code had become tangled. Nothing new would grow.”

A good gardener helps maintain the conditions for growth. So does a good technical writer. – Doug Bedell

Comments

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

Comments

Email Subscribe

Recently


Categories


Archives


Blogroll