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.

Keep the Insights Churning

Posted on July 30, 2015
Filed Under Communication, Technology | Leave a Comment

Technical writers may not realize it, or always act on it, but they’re positioned to know a lot about their organizations, more, perhaps, than most of their colleagues. That’s because they’ve traveled their reaches looking for what we might call linking insights, and have mulled over those they’ve received.

imagesCraig Haiss on his HelpScribe blog is good at paying heed (and minding his manners) on his technical writing rounds.

“There are ways,” he writes, “to infiltrate the minds of your coworkers and make an indelible impression of your worth. But you have to make a proactive effort.”

“Don’t let the routine lull you into an apathetic state,” Craig urges. “You job is not about what happens to you. You can meet your deadlines and still find ways to meet other key players in your business. Look for projects outside of your department that could benefit from you technology and communication skills.”

They you have it: Not everybody, far from everybody, in fact, has both technology and communication skills. Treasure what you’ve acquired, along with the instincts you were born with. If you’re not learning, you’re likely wasting the time you’re spending on your daily rounds.

Or maybe, by organizational fate or mistaken fiat, other departments are working on the same things you are. Should you note that, do something about it. “Payroll is pricey. Tools are pricey,” Craig notes. “When two or more people are documenting the same process with different tools, your company is losing money.”

That’s the style of an activist writer, not a mere transcriber of observations made on fitful rounds.

“Only you can help others realize how valuable an asset you are,” Craig notes. That’s true, but you have to act like an asset – by making connections others may be missing, and by noting needs and issues that may have been overlooked.

Yes, a technical writer functions, or should, in the mode of what the newspapers used to call a beat reporter. Newspapers are fading now, unfortunately. Don’t let that be the fate of your technical beat. Your organization can’t afford it, nor can you. – Doug Bedell

Dr. Quick’s Knowledge Reaped World Harvests

Posted on June 24, 2015
Filed Under Communication, Technology | Leave a Comment

The vast range of human technical ingenuity is brought home, sadly, by the death of Dr. Graeme Ross Quick, an Australian whom most of us never heard of.

The Land, an Australian blog, advises that Dr. Quick “was an authority on harvesters, tractors and much more.” He died last month at the age of 79.

2133390An authority on harvesters? Don’t they just grind across a field, bringing in a crop? Not if you’re a farmer they don’t. They’re highly specialized pieces of technical equipment.

What you come to know depends largely on where and how you’re raised, and what experiences and opportunities you’re exposed to. Dr. Quick was raised in Australia’s Victoria state and developed a fascination with farm equipment “on an uncle’s nearby farm where he helped stock sheaves and worked with a horse-drawn reaper and binder.”

Farm work “helped fund his studies for a University of Melbourne degree in mechanical engineering, also sparking a career-long interest in field equipment efficiency.” What you influence, thereby, is what you become increasingly attached to.

Graeme Quick and his wife, Marlene, moved with their three young boys to the U.S. in 1967, where he accepted an invitation to teach and study for a doctorate at Iowa State University. His later career took him to Norway, Canada, the Philippines (where he headed the International Rice Research Institute’s agricultural engineering division), and then to the United Nations Food and Agriculture Organisation (FAO). “His rice research and FAO projects,” the FarmOnLine writers add, “took him as far afield as Egypt, Pakistan, Bangladesh, Vietnam and Bhutan in the Himalayas.”

That all made him an international technical advisor in harvesting. Think how much of an increased yield resulted from his work! And he became the first Australian fellow of the American Society of Agricultural Engineers. Obviously, you don’t give accomplishments like these any thought if you’re not aware of them.

Finally, Dr. Quick received agricultural engineering’s highest recognition – the C.H. McCormick-J.L. Case gold medal “for meritorious contributions to the profession.”

How many such technically grounded men and women, largely unsung heroes and heroines of our times, do you know? Don’t you wish you knew more of them? Be alert to where they might be active in your field, and seek them out. In this Internet age, that’s becoming easier to do. You’ll grow together, harvesting wisdom. – Doug Bedell

Moreover, Writing Takes Time to Do Well

Posted on June 9, 2015
Filed Under Communication, Government, Technology, The Writing Life | Leave a Comment

Here’s Tom Johnson, the technical writer proprietor of “I’d Rather Be Writing,” trying to make amends – and offer cautions – for all our heedless brethren who aren’t so mindful that, after all, they’re dealing with human readers, even if they may have technical mindsets.

Businessman sitting at his desk lost in thoughtReaders turn to a technical text to learn efficiently. But, too often, they’re imposed upon by writers who don’t take the time to be readily understood. Yes, coherent technical writing takes time, along with an understanding of its context.

The first thing we need to do, Tom notes, is to “decode complexity”. But if complexity is presented well, it can take less time to cope with – good technical writers take the time to save their readers time. (Their employers need to be mindful of that.)

Densely driven technical writers are prey to the main hazard of all heedless writers – they risk not being readily understood. Who would sit down to a keyboard these days and not want to be readily understood? Only reckless or inordinately pressurized souls. Be sure you own situation is fairly structured to allow you to read and write well. (Clue: Communication with managers may be required.)

Yet you also have to apply shoe leather. Part of being a good technical writer, Tom notes, is being an investigative reporter. You need to seek out information from its sources – the actual “doers” in your work setting.

“I set about asking engineers around me for information,” he writes. “Every time I talked to an engineer, I would get a firehose of useful information that would help me understand what was going on.” You’re there, basically, to slow down and aim the hose so that others don’t get sprayed with information.

Tom suggests that stepping through a task yourself, if you have the time, is a good idea – and you should have the time. (Again, supervisors please take note.)

And finally, the best advice: “Rest your brain. Sometimes,” Tom notes, “when I can’t figure something out, I sleep on it. In the morning, the answer comes to me.” Or simply take a break.” Indeed, a good cook will tell you that recipes can’t be rushed. Technical writing’s no different. – Doug Bedell

Writing That Gets You From Here to There – Now as Then

Posted on May 11, 2015
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Tom Johnson, a technical writer in San Jose, CA, has the right idea: He wants to be sure that technical writing is focused on the reader (that is, the user), not the equipment or processes being explained. They’re obviously important, but the reader is moreso. He or she has got to get it right – and readily so.

imagesTom has started a new series on his I’d Rather Be Writing blog on user-centered design. That’s what all good writing should be: user-, that is, reader-, centered. It’s not the equipment or location that’s benefitting from clarity of expression – except residually (it can be damaged) – but the reader who’s seeking to use it properly. And he or she may be in too much of a hurry.

All good writing puts the reader foremost. Not that writing needs to be overly simplified, but it needs to be engaging – or, in the case of technical writing, readily decipherable.

Tom Johnson has spent some time in usability labs watching users interact with his content and, he says, “it’s an eye-opening experience.” He’s got some links in his post relating to the labs, but he’s distilled 12 patterns from them. They include recognizing that users are often in a hurry, that they like visuals and that they don’t necessarily read in sequential order.

Meeting such human desires is indeed a challenge to technical writers, but those are your publics – human beings under pressures.

Tom Johnston writes not not so much about instructions for physical products as software documentation, which is his gig. Yet clarity applies as much to today’s cyber settings as it did to Thomas Hardy’s Wessex novels.

Tom Johnson urges his tech writing colleagues to design their documentation around his perceived patterns of user behavior. In listing them, he’s done a lot of your work for you. Take advantage of his accomplishments. – Doug Bedell

(Illustration: Simon Gatrell’s book “Thomas Hardy’s Vision of Wessex”)

Technical Writing’s For Real, Steph

Posted on April 9, 2015
Filed Under Communication, The Writing Life | Leave a Comment

We were browsing for an Insights post and came upon Technical Writing World, an interesting-looking “social network for technical communicators”. Yet, there it was, in the very latest post, by one Steph Hepner to Lia Pi, apparently a member of a college class somewhere:

“Hi, this is my experience. I didn’t watch my grammar or composition, so please don’t think I’m a bad tech writer – I was just lazy and in a hurry! You may contact me if you have any questions or I answered yours incorrectly…”

tw101Well, thank you, Steph, for the antithesis of good technical writing. We learn sometimes, don’t we, by going to extremes? Well. the extreme for good, orderly technical writing is 1) Being lazy, 2) Being in a hurry and 3) Leaving the reader guessing, puzzled or confused.

You couldn’t boil the craft down to a more succinct core than that.

Maybe technical writing, though, doesn’t belong on a gossipy, we’d presume, social network like this one. Yet Technical Writing World appears to be devoted to the craft itself. Or, maybe we’re missing the difference between conversation and a craft. To be kindly, we’d allow that that’s what occurred here.

The trouble is that technical writing is pretty demanding, even in its “social mode”. What if, under pressure, a technical writer should lapse into his or her social media guise? That wouldn’t be good for him, her, the craft, or the enterprise involved, would it? Or is there a difference between the standing of the craft and given practitioners thereof? We’d hope not.

The heart of what we’re trying to suggest is that good writing is a discipline, one that’s practiced whenever fingers touch upon a keyboard. Suppose a concert pianist began doodling “in public,” which, after all, is what writing on a social network amounts to – conversing in written form in public.

No, Steph, we don’t think you’re necessarily a bad technical writer, just a reckless one when it comes to communicating outside your cubicle. Or were you in yours when you wrote this post? If so, shame. You don’t need to be stuffy, just careful, orderly and certainly not in a hurry. – Doug Bedell

A Tech Writer’s Requirements: Curiosity and Clarity

Posted on March 10, 2015
Filed Under Communication, Technology, The Writing Life | Leave a Comment

imagesIt can be argued that technical writing is a higher form of writing than other types of written expression. Or if not a “higher” mode, than a more demanding one, in that there can be prompt physical consequences to technical jottings. Technical writing provides directions for acting in physical space – it needs to be clear and accurate.

Instructional materials are consulted with a presumption of expertise and diligence on the writer’s part. And yet, what goes into assuring that directions and procedures are accurate and useful? What are a good technical writer’s most important traits, his or her most essential operative values?

Technical proficiency is needed, but it may not be enough. Sharon Burton, a veteran California technical writer, feels that curiosity, plain and simple, is a key requirement. “I can teach someone to write,” she says. “What I can’t teach is the curiosity to ask questions, to poke at the product, to constantly ask ‘What if…?'” Indeed, whatever it is that makes something functional (and, of course, safe) is of key importance. There’s no mistaking that.

Once you’re confident about the scope of a process, and are ready to put it into words, clarity and economy of expression are required. At Encore Technical Resources, proprietor Dennis Owen feels that a technical writer’s most important trait is “to thoroughly understand a process, so that you can write about it in a logical sequence. It needs to be a well-written, intelligible path to be followed.”

Curiosity and clarity – two values central to good technical writing. We try hard to make them Encore’s hallmarks. Unlike the often fleeting satisfaction that comes with completing a gripping work of fiction, technical writing can have immediate and lasting consequences. They need to be the ones intended by the writer from the start, the fully predictable results of all that’s been invested in his, or her, craft. – Doug Bedell

Western Mentors Instilled Technical Writing in China

Posted on December 22, 2014
Filed Under Communication, Education, Technology, The Writing Life | Leave a Comment

9PTihGoCtzfdHI56NwgR

Here’s a remarkable discovery on our part, illustrating anew how cooperative and interrelated our world can be if we let it. Bet you thought China somehow picked up its technical expertise on its own, enabling it to run rings around the U.S., in some respects, unassisted. Well, that’s not really so. No more than it was when W. Edwards Deming made his first trip to Japan in 1947 and started a quality transfer process there that initiated “Japan’s economic miracle”.

We’re learning from a post by Shannon Li on the Sigma Technology site that international contacts and cooperation have evidently been as important to China for technical communication as Deming-initiated quality awareness was for the Japanese. In 1997 a team of 12 technical communicators from the U.S. and Canada headed by Sam Dragga from Texas Tech University visited China and found it “hungry for technical communication education.”

“With no profession and independent academic discipline here,” Li writes from Beijing, “China was hungry for technical communication education. At that time, the English department trained translators, interpreters and tour guides for business and government organizations. Although there were courses like professional English and English for science and technology, the focus was on professional vocabularies and terms instead of on technical writing.”

So, by gosh, a group of 50 English teachers from colleges and high schools in Jiangsu Province attended lectures by the U.S./Canadian team and prepared six-day courses from them that included topics “like technical communication history, cross cultural communication in technical writing, audience, document design, types of technical writing, etc.” Between the lecturers and their Chinese students, technical writing began taking root in China.
Read more

Note-taking as a Productivity Prod

Posted on December 9, 2014
Filed Under Business, Communication, Technology, The Writing Life | Leave a Comment

imgresTaking notes isn’t simply scrawling a snapshot of what you’ve read so that you can recall the details later on. Technical writers, especially, should be mindful that note-taking can be a memory jog for inspiration itself – that is, it has a wider function than just “recalling”. It can be a prod for creative advances.

We are reminded of the creativity-prompting potential of note-taking via an edutopia post by T.R. Girill, of the Society for Technical Communication at the Lawrence Livermore National Laboratory.

There were, of course, as Girill observes, the field notes of Henry David Thoreau “on the flowering times of 500 plants near Concord, MA (that) are still used today for comparison with current climate-change data.” But, as he continues, most notes “are used by an audience of one”: yourself. Yet they can extend your reach widely.

Thus, Girill cites Eric Green’s chapter (Ch. 12) in Michael R. Canfield’s book, “Field Notes on Science and Nature” (Cambridge: Harvard University Press, 2011) in urging science students – we’d add practitioners, too – to extend the scope of their note-taking “beyond just observations or numerical data” to include such utilitarian matters as:

“• Memory aids, about places, times and conditions that could be helpful later but will be forgotten if not captured now.
“• Organizational Aids, cross references and page indexes (easiest if the notebook pages are numbered), especially for long projects.
“• Commentary – any remarks that could generate new ideas or improvements on old ideas.”

Writers and reporters have been mindful of the memory-prodding value of notes for ages. Thus the piles of notebooks and other materials that you’re apt to find in the vicinity of newspaper reporters and writers, or at least were, before the acquisition of digital data became so prominent. (We remember the table behind the desk of one reporter at the old Philadelphia Bulletin that was piled so high with notebooks and other source materials that it nearly triggered a newsroom pool as to when it might topple over.)

Girill’s post includes further prompting on memory-jogging techniques stemming from good note-taking. We’d simply restate what should by now be obvious – that the more you earnestly record, the more you’re likely to usefully recall at some especially auspicious point later on. Note-taking is well worth the time involved in jotting informative encounters amply down. – Doug Bedell

Effective Writing Isn’t Necessarily Sparse Expression

Posted on November 21, 2014
Filed Under Communication, The Writing Life | Leave a Comment

There’s a lot of interest in the subject, or style, of minimalist writing – using the fewest words possible to make a point, have impact, be clear. Google the subject, and you’ll find lots of links to a yeasty (that is extensive, rather than minimal) debate. Within limits, being sparse is admirable, so long as you communicate what you’re aiming to say. Ernest Hemingway was one of the early masters of modern minimalism, and his writing is gripping, whatever a comparative word-count with earlier writers might be.

Efficient writing? It all depends on the purpose involved.

Technical-WritingGood writing, actually, is a form of good manners. It’s an imposition on readers to confront them with verbosity, unnecessary words added for “show”. By now, that should be an inarguable literary principle. Good writing, though, isn’t always minimal writing – it’s appropriate writing, well-suited to the characters, purpose or setting being presented in words.

In the discipline of technical writing, we’d add the all-important element not merely of purpose, but specific purpose. In providing instructions to readers on how to accomplish a given procedure both efficiently and safely you want to be as clear as possible. In a technical context, clarity often means providing necessary details and cautions, while in minimalist fiction too many details or grammatical complexities might be considered an imposition on the reader.

In effective technical writing, you want to provide all the necessary details, but in as economical, that is as orderly, not necessarily as sparse, a manner, as possible.

On Google, you’ll be lead, right off, to a post by Jessica Dang on her Minimal Student blog. She is devoted to principles of minimalism in living, not only in writing. But her “Complete Guide to Minimalist Writing,” runs on a bit, presumably what happens when you are highly enthusiastic about a subject.

Writing comes down to a style appropriate to the purpose and need involved. Excessively sparse instructions – we’ve all encountered them – can be frustrating, as annoying as plot twists we’ve not been adequately prepared for. In technical writing, you’re not seeking to create a mood or resolve a crisis, but to avoid one. You’re promoting a mode of safe, economical action, and that takes a fully appropriate body of words to accomplish. – Doug Bedell
 

A Tech Writer’s Priority: Striving to be Clear

Posted on October 20, 2014
Filed Under Communication, Technology | Leave a Comment

eggs-unhappy

When communication doesn’t work, becomes too dense or defiant, who’s at fault? Why,  you’ll say, the technical writer who created the offending material. Could well be. Yet Mark Baker on a Tech Writer Today post, says the reader, as well, has a role to play in coping with printed material. But, definitely, that’s not to let the writer off the hook.

“The curse of knowledge is, of course, a real and serious matter,” Baker writes. “And a good writer is certainly one who is aware of, and able to compensate for, the curse of knowledge, at least to a degree. But the problem with blaming the failure of communication on the curse of knowledge alone is that it leads to the expectation – which (Stephen) Pinker (in a cited New Yorker essay) explicitly states – that the cure is ‘to explain the jargon, or spell out the logic, or supply the necessary detail.'”

Of course, a technical writer should be as accessible as possible to his or her readers. But the cure for dense writing, Baker argues, isn’t simply more words in the presumed interest of clarity. It’s to expect a reader to make some effort to understand what you have tried to present, provided that you, the writer, have indeed tried diligently to be clear. Due diligence becomes the key.

Baker advises technical writers that “One of the most important things to remember when providing such resources is that the reader’s goal is not to understand what you have written. A meeting of the minds is not what the reader has in mind when they crack open a technical manual. Fully understanding the contents of the writer’s mind is not what the reader is aiming for. Rather, their aim is to understand something useful about the real world.”

That calls, perhaps a bit more simply, for a technical writer to approach his or her material in the spirit of empathy, or walking in a reader’s shoes. Before tackling the material, a technical writer, like all writers,  should be thinking, “Now, who will be reading this, for what purpose?” You’d think that would be self-evident for instructions to a shared workplace or the equipment therein. But not really. People, even colleagues, come to writing from all sorts of backgrounds and levels of experience.

You’ve got, first, to think clearly about “What am I trying to get across here, and what’s the most accessible way to do it?” Not simply plunge into the instructional task, even if you face some sort of deadline for completing it.

Stepping into a reader’s shoes is  mandatory for any sort of successful writing, technical instructions included. With that done, instructions become guidance, and who doesn’t appreciate effective guidance? – Doug Bedell   

« go back — keep looking »
Email Subscribe

Recently


Categories


Archives


Blogroll