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

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

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

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

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

Virtual Reality at Elevator Doors? – Indeed So

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

imgres-4Looking 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

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