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.

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.

Readers 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

Comments

Mars Photos Keep Coming Over Those Millions of Miles (Make that Hundreds of Millions)

Posted on May 26, 2015
Filed Under Education, Technology | Leave a Comment

Go on a springtime tour of Mars, our Spring at least. The National Aeronautics and Space Agency (NASA) is posting a series of photos taken by its Curiosity Mars rover over periods of days and months. There are shots of Curiosity climbing a Martian mountain and even of “a serene sundown on Mars.” (Click on this photo for a sharper view.)

Such a photo gallery is a truly amazing accomplishment, considering that it’s coming from an average distance between Earth and Mars of 140 million miles. It may seem like wasteland, but put that into the context of the solar system, and what it took to get there and there is much to ponder about extra-spatial relationships.

Not content with the merely amazing, NASA recently reported that it has succeeded in sharpening the focus of Rover’s camera to get more sharply etched shots of the landscape there. How? By sending new software up there, of course.

Comments

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.

Tom 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”)

Comments

Good Writing Requires Empathy Always

Posted on April 22, 2015
Filed Under Technology, The Writing Life | Leave a Comment

The craft of writing, technical or otherwise, is a demanding one – surely you’ve heard that?

Stephen Pinker, Johnstone Professor of Psychology at Harvard University and chairman of the Usage Panel of the American Heritage Dictionary, discusses that reality in a Wall Street Journal post. Only he attributes the difficulty to the wrong source, or at least doesn’t go deeply enough into the problem.

It’s not so much that writing is so much a demanding exercise as a somewhat deluding one. You’ve gotten those words onto paper, they flow before your eyes, so they must be the delightful outcome of a trying process. Oh, really?

The difficulty in writing well – so that your output isn’t opaque or appear as next-to-gibberish to someone else – is that you, the writer, may be lacking in a sense of empathy. Relax, that’s not fatal, but it takes awareness to correct. Empathy is best defined as walking in someone else’s shoes or, in this case, reading with someone else’s eyes. How am I coming across not to myself, but to my readers, should be every writer’s question, constantly.

Forget the recognition you may have justly earned for your accomplishments. When a page with your words on it is put before someone else, all that matters at that moment, besides the basic accuracy of your expression, is how well it connects with the reader, how well it informs or inspires others.

Pinker discusses bad writing in terms of the “bamboozlement theory” of written expression. “Pseudo intellectuals,” poor writers who consider themselves good ones, let themselves off the hook too easily – if they even realize that they’re on a hook.

“The curse of knowledge,” he writes, “is the single best explanation of why good people write bad prose. It simply doesn’t occur to the writer that her readers don’t know what she knows – that they haven’t mastered the argot of her guild, can’t divine the missing steps that seem too obvious to mention, have no way to visualize a scene that to her is as clear as day. And so the writer doesn’t bother to explain the jargon, or spell out the logic, or supply the necessary detail.”

In other words, he or she (sex doesn’t matter when prideful creation is underway) doesn’t empathize enough with the reader. “How am I coming across?,” “Am I being understood about what I’m trying to get across?” should be his or her recurring thought.

Walk in another’s shoes while writing and you may get to a different place than you intended, but you’ll have others with you. And it’s always great to have company, real companions, not simply assumed ones. – Doug Bedell

Comments

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…”

Well, 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

Comments

Mischief Lurks Amidst the Data

Posted on March 25, 2015
Filed Under Business, Technology | Leave a Comment

Wow, the sheer scale and density of information on the Internet, not to mention corporate computer networks apart from the web, is becoming mind-boggling, and a growing opportunity for cyber mischief, intentional or by happenstance. Technical writers need to pay heed to what’s going on around them in this regard.

Mark Schaefer in his engrossing new book, The Content Code, discusses “content shock,” and points to “a 500 percent estimated increase in the amount of information on the web between 2015 and 2020. If you can imagine the vastness of the web today…well, pretty soon we’re going to have five times that! And some think that number is low, projecting as much as a staggering 1,000 percent increase in information density in that timeframe!”

Schaefer adds that 75 percent of this information increase will be coming not from automated sensors in homes and on highways, the long-anticipated Internet of Things, but from brands and individuals. “Nearly every person on earth is becoming his or her own personal broadcast channel,” he advises.

So what is a conscientious technical writer to do in the face of an information tsunami? Simply shrug it off and continue adding his or her own rivulets? Partly that, of course – completed pages, assignments and newly authorized documents prompt paychecks.

Yet from within the deluge promptings toward order, economy and clarity of expression would seem to be increasingly advisable. Sanity, not to mention safety, comes in providing reliable guidance and making such output as accessible as possible to its intended consumers.

But still, the mass of data available on local servers is an invitation to mischief or, to be less discreet, prying and spying. Chris LaPoint, Vice President of Product Management at SolarWinds, writes on the Technically Speaking blog that “insiders are starting to supplant external hackers and terrorists as the greatest cybersecurity threat.” In a SolarWinds survey of federal IT pros, “more than half (53%) of the respondents identified careless and untrained insiders as the greatest source of IT security threats at their agencies, up from 42 percent last year.”

So, it would seem that a responsible technical writer needs to be attuned not only to his own computer screen and keyboard, but to what is occurring around him as he pursues his work.

Mischief might not always be intentional, sometimes it’s the result of sheer sloppiness. Along with the increasing volume of network traffic, “the growing use of personal devices is another factor, as is mounting pressure for IT pros to change network configurations quickly, rather than correctly. Combine these issues with simple human error – a misplaced USB drive here, an unattended laptop there – and lack of training, and one can understand how insider threats can loom so large.”

It’s no longer that growing amounts of internally generated information are merely unwieldy, they may also be hard to safeguard, that is, to police. Let conscientious technical writers be mindful of that. – Doug Bedell

Photo – zazzle.com

Comments

A Tech Writer’s Requirements: Curiosity and Clarity

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

It 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

Comments

Digital Risks Growing With the ‘Inclusive’ Web

Posted on February 27, 2015
Filed Under Technology | Leave a Comment

We pass this post from Technically Speaking along as much for its graphic as its written contents, though both highlight how interconnected our world is becoming, and how security concerns are rising along with digital proliferation.

Yes, the “Internet of Things” is both awesome and alarming. The term dates back 15 years and refers to “the next evolution of the internet when everyday objects are networked to the web and each other.” Smart watches, connected cars, appliances and houses are examples.

Even the Department of Defense is into internet connectivity, for such mundane functions as managing its vehicles, trash pickup, and inventory management, along with piloting airborne drones and driverless vehicles.

The problem is that “smart ‘things’ don’t come without risk…as the rate of connected devices rises exponentially, the number of hackable things does too.”

The post includes further reflections on the growing, unwelcome detectability of technical and security information, and we recommend it to your earnest attention. We can’t have digital devices, it appears, without growing digital risks. At the least, be sure you’re keeping your anti-virus software updated. And try your best to keep abreast of our digitally diverse world. – Doug Bedell

Comments

Being Saved: Restoration of the Original ‘Air Force One’

Posted on February 11, 2015
Filed Under Government, Technology | 1 Comment

Our colleague at Encore Technical Resources, Dennis Owen, knows a good story when he sees one. Hence, he’s passed along the tale of the first Air Force One, the aircraft used by President Dwight Eisenhower, which is now languishing in faded glory at an Arizona airport. Mary Jean Eisenhower, Ike’s granddaughter, thinks it deserves better, and so it does, for it’s a national treasure. Fortunately, Mary Jean’s close to bringing about the plane’s salvation.

Who doesn’t perk up a bit on hearing that Air Force One is carrying the President of the United States on a leadership mission somewhere in the world? Well, the first Air Force I, a sleek, silvery Lockheed Constellation VC-121 named Columbine II, initially had mere call letters, but it once nearly got mixed up with a commercial plane with the same designation. “After that,” Mary Jean notes, “any aircraft with the president onboard was designated Air Force One, no call letters.”

Placed in White House service in 1954, Columbine II’s last flight was in 1959. When the Eisenhower Administration ended in 1960, it was, first, returned to the Air Force fleet, then sold as part of a group of five planes that were intended for use as crop dusters in Arizona. But somebody from the Smithsonian went looking for it and it’s been the beneficiary of good, increasingly encouraging intentions, ever since.

Fairly confidently, Mary Jean Eisenhower notes that Columbine II is now destined for restoration to flying condition and a home at the National Airline Museum in Kansas City. May that prove so, for the original Air Force I is part of our nation’s history. As Columbine II, it carried President-elect Eisenhower to Korea to fulfill a campaign pledge that he would go there to seek to end the Korean War. And Queen Elizabeth II was one of its last passengers.

Why the name Columbine? Well, Ike’s granddaughter recalls, that was the name of the plane that General Eisenhower used in World War II; it, and all the other aircraft he used then, were named Columbine, after the state flower of Colorado. That was because his wife, Mamie, was from Denver. President Eisenhower’s Atoms for Peace speech was written aboard Columbine II. And his granddaughter knows where the silverware and china that were used on the plane are located.

The public can help in the plane’s restoration by visiting its website at www.columbineii.org. The goal is to have it ready for flights again by the end of this year.

The great insight from this tale is that everything of value worth remembering or restoring has a story, a history we want to hold on to, not leave languishing somewhere in a desert of the mind. – Doug Bedell

Comments

Help Government Become More Digitally Engaged

Posted on January 25, 2015
Filed Under Government, Technology | Leave a Comment

Opportunity for technical writers comes in knocking when you’ve got doors to knock on, whether they be in the private or public realms. Here, from David Kimball, in Austin, Texas, is a reckoning of “Five Government IT Professionals Who Will Be In High Demand in 2015.” David is the “group vice president of federal” at Austin IT management software provider SolarWinds.

The five areas in which government needs IT pros, as David sees them, are The Diagnostician, The Developer, The Data Ninja, The Cloud Database Administrator and the Security Mobility Guru. This last refers to IT pros who can protect agencies from digital intrusions in “the age of the Internet of Things, with mobile connected devices (read: potential threats) seemingly everywhere…”

Yes, digital expression is a new form of communication that government agencies are beginning to take really seriously. Witness, for example, the “National Conversation” on Security Technology that the Department of Homeland Security is sponsoring.

“Great needs lead to great demand,” David Kimball notes. There are plentiful opportunies for IT pros to shine as way-showers to government agencies, as his helpful post makes clear. – Doug Bedell

Moreover, Writing Takes Time to Do Well

Comments

Mars Photos Keep Coming Over Those Millions of Miles (Make that Hundreds of Millions)

Comments

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

Comments

Good Writing Requires Empathy Always

Comments

Technical Writing’s For Real, Steph

Comments

Mischief Lurks Amidst the Data

Comments

A Tech Writer’s Requirements: Curiosity and Clarity

Comments

Digital Risks Growing With the ‘Inclusive’ Web

Comments

Being Saved: Restoration of the Original ‘Air Force One’

Comments

Help Government Become More Digitally Engaged

Comments

Recently

Categories

Archives

Blogroll

Find It