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.

An Awesome Web Community

Posted on April 20, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

We need to tip our hat, or maybe more, to Technical Writing World, the “social network for technical communicators.” Yes, more – so we’ll blog a bit about the site. Why? Because it’s got over 2,800 members, and that’s great for a social network that’s not Facebook or Twitter.

What’s all this gushing about? Well, we’re halfway through our second reading of Mark Schaefer’s latest book, “The Content Code,” which describes in detail how hard it is to get discovered on the Web these days, and how it’s getting even harder.

What Technical Writing World’s impressive membership indicates is that technical writers are discovering each other in a world-wide community of engaged, conscientious people. We knew they were conscientious, of course, but to join and sustain a worldwide community like TWW is exemplary these days.

For the Web is like a vast sea that’s getting ever wider and deeper, one where it’s increasingly hard to be found and engage with other colleagues. We look at Technical Writing World and all sorts of sharing seems to be occurring there. There are 189 blog posts, 607 forum discussions, an upcoming event next month of the Society for Technical Communication, leaderboards to promote the most active members and their contributions, a Techcomm Superfeed with the latest blog posts from members, and postings of technical writing jobs. (Might this be a special reason for the site’s popularity?)

“I’ve spent the last year studying this essential concept of content ignition, Mark Schaefer writes in ‘The Content Code,’ and it has changed me. There is a science and psychology behind the act of sharing content that is awe-inspiring and beautiful and mesmerizing. People share content for hundreds of reasons, but there is a uniform process behind it inexorably linked to self-image, caring for others, and even compassion for an author or brand.”

Well, nobody seems in need of compassion on “Technical Writing World,” but it is indeed an awe-inspiring site, a testimony to the communal challenge, satisfaction and sharing behind technical writing taken seriously and collegially. – Doug Bedell

Economics Without Weeds

Posted on March 29, 2016
Filed Under Business, Technology | Leave a Comment

We’re penning this commentary on a post by Jim Grey (on his Stories from the Software Salt Mines blog) not only because we like the graphic (left) that runs with it, but because it gives the lie to the notion that economics are nearly everything in business. Creativity, focus and flow count for a lot too.

Jim’s noting, and complaining, that Silicon Valley tech companies appear to be moving their tech support departments to middle America because they can pay support techs less there. Let the support folks answer phone queries from the boondocks, rather than the coasts, is what it amounts to. Yet that’s a profoundly mistaken view if a company’s more creative people are on the coasts. If creatives aren’t housed with the support people, we’d counsel, watch out!

Over time, a tech company might well be denying itself insights that could make it’s products better and more customer-focused, because they’re not being made in a system in which front-line customer/technical feedback is being readily heard. A system implies activity centers in a configuration that readily and productively support each other.

“Support,” Jim Grey writes, “really can be a good place to grow talent for other teams because techs know the products and, more importantly, how users actually work with and experience them.”

Who’d a thunk? That’s what happens when support people spend all the time they typically do with confused and possibly disgruntled users. Why deny a firm’s “creative” people the insights they garner or have them coming in secondhand, from the heartland to the coast?

Stupid, stupid. “Here in the Midwest, where cost of living is generally low,” Jim observes, “the startup, small, and medium-sized companies where I’ve worked don’t outsource customer service. Those workers are already plentiful and inexpensive. And so support is always down the hall or on the next floor. Developers and testers become friends with many of the support techs.”

So why doesn’t Silicon Valley see the benefit in having everybody together, too? Can it be economics alone – if so, it’s a false sense of economics. Or is there something of a caste system at work as well – “creatives” and everybody else. If so, and again, that’s simply stupid.

Take down the “Road Ends” sign in the photo and yank out those weeds. We’re all in this together, designers and enablers alike. That’s the best kind of economics. Amen. – Doug Bedell

Getting ‘Out There’ Matters Greatly

Posted on March 11, 2016
Filed Under Technology, The Writing Life | Leave a Comment

On his ‘I’d Rather Be Writing’ blog, Tom Johnson in California’s San Francisco Bay area takes the occasion of moving to a new job to reflect on what he was pleased with, and not so pleased with, on his old one. His reflections reveal a conscientious, fully engaged technical writing style, although not a perfect one – on his old job, anyway.

Tom’s first priority, a key resolve, seems to be getting out to where the work is done, to experience what’s happening before he prescribes procedures to keep it happening.

“Understanding the scrum process and how it was implemented,” Tom notes, “allowed me to quickly understand what teams were working on and what documentation needed to be written or updated, and when.”

Like a street-side reporter, you have to be on the street, rather than at your keyboard, to experience what’s actually happening before you start to describe it for others. There’s nothing like “being there” as a first step.

“I like being a part of engineering teams,” Tom notes, “embedded right there alongside product managers, quality assurance engineers, and developers. I built a strong sense of trust and rapport with the teams. I don’t like it when writers are grouped in their own space and interact mostly with each other, separated from the engineers.”

In getting to know the engineers he’s writing for, Tom is almost automatically in closer touch with them – they’re colleagues, not clients in their own “spaces”.

“I learned,” Tom confides, “that you should never send blanket emails to the entire team asking for reviews of massive amounts of documentation, because it will never happen.”

His goals for next time include trusting nothing, testing everything; keeping documentation systems as simple as possible and “diving deep into content, not doc tools.”

This all gets down to becoming, and remaining, authentic in your approach to technical writing. It may seem initially comfortable to be sitting at a wide display with a slick keyboard, but, over time, it’s the content, more than the technique that matters. And you get that from your colleagues. After all, they’re doing the work you’re describing. – Doug Bedell

Bless Her, Sarah’s All For Sharing

Posted on March 6, 2016
Filed Under Technology, The Writing Life | Leave a Comment

Cheers to Sarah Maddox for taking us (virtually) to the TCWorld India 2016 conference held recently in Bangalore. “It’s been an amazing, rewarding experience,” Sarah, writer of the Ffeathers technical writing and fiction (there’s a combination) blog, notes. “Here are some of my impressions, and a roundup of the posts I’ve written about the sessions I attended.”

What follows from Sarah, who’s from Sydney, Australia, is the next best thing to being at the conference, photos of the event but more to the point, her notes on the sessions she attended. These include topics like “The Future *I* Technical Communication”, which was Sarah’s keynote to the meeting, with 71 slides.

There’s easily a week’s material on technical writing here, all from an energetic, community-minded woman who enjoys sharing her insights, big time. Thanks Sarah!

The photo, of a dance party at the conference, shows that everybody had a great time learning! – Doug Bedell

Improving Toward a Summit – a Constant Process

Posted on February 25, 2016
Filed Under Technology, The Writing Life | Leave a Comment

What’s “done” in terms of technical resources these days? Probably nothing, at least in the realm of process and methodology. Both are open-ended and need to be so to allow for improvement, for adding new features and reaching higher, more refined “ends”.

Process improvement is actually an endless process. It needs to be conducted as though an “ending” is beside the point. A pause for evaluation and insight, yes. An ending, no, not if you’re steadfastly open to learning and improvement.

What’s prompted these advisory reflections? This time, a post on Technically Speaking by Rick Stewart headed “Modern Software Development: A Continuous Journey, Not A Delivery Destination.”

“But I’m not into software,” you say? “Everything needs to have a finished state.” No, it doesn’t, and shouldn’t. Software aside, there’s a better way to brew a cup of coffee, not one you’d want to come upon every day, but a new bean or filter that makes an appreciable difference. You don’t want to go back to the old way of brewing now that you have this new cupful in hand. Life’s ever-unfolding promise is demonstrated anew.

Rick Stewart could learn more about writing. His paragraphs are too long and unwieldy. But the insights are there nonetheless. The words were worth spilling out, now they’re well worth improving upon.

Rick is writing about hiking in the Shenandoah National Park to a “spectacular summit”. It was a lot of fun for his family and friends with great views along the way. Why expect readers to plow through dense paragraphs to get there themselves?

The lesson in all this is to ask a constant question: Have I done this well-enough or really well? Well-enough may be okay for today, really well is a lifelong aim. – Doug Bedell

Technical Writing Is Like Other Writing Done Well

Posted on February 16, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

What is this craft of technical writing that we’re engaged in? And why should we be fussing with a question like this? Instead of defining our activity, why don’t we just settle down and do it?

Well, you’re right, we could just get on with it. But definitions, even for words or activities we know well (don’t we?), are useful. They bring clarity and may remind us of aspects of a task that we’ve overlooked or would rather not be reminded of.

TechWhirl responds to this question with a simple, three-word phrase. (See, if you get serious about something, you can simplify it.) Technical writing is “simplifying the complex.” Yes, that’s simple enough, but is it truly enough? When you head over to Oxford Dictionaries Online, four definitions are provided for the word technical alone.

TechWhirl notes that the U.S. Bureau of Labor Statistics “defines technical writers as those who ‘…put technical information into easily understandable language.'” That’s simple and direct enough, especially for a government agency.

Yet maybe we should note TechWhirl’s long-form definition: “Good technical writing results in relevant, useful and accurate information geared to specifically targeted audiences in order to enable a set of actions on the part of the audience in pursuit of a defined goal.”

That whopper hinges on instructional audiences and their goals – presumably, accomplishing a critical task efficiently and safely. To act efficiently and safely, you need instructions that are clearly written and presented, along with being accurate.

Simple enough, right? Yes, but first, you need to be a master of the process in question to write about it authoritatively and efficiently. Not just the process, but, equally important, the context in which it’s being applied. (We keep thinking back to our years spent working in nuclear power plants.)

TechWhirl discusses a number of other elements, but they’re mainly on the order of fine-tuning. The essence of the matter is that a good technical writer needs to be authoritative and focused on his reader in pursuit of a common goal – accomplishing a task efficiently and safely. That, incidentally, is how Hemingway might have described his writing as well. It’s all a matter of context and being effectively other-focused.

(The graphic above is from a LinkedIn SlideShare presentation by Muhammad Ilyas.) – Doug Bedell

A 2016 List From Tom Johnson

Posted on February 5, 2016
Filed Under Technology | Leave a Comment

Because we value Tom Johnson’s “I’d Rather Be Writing” as a technical writing blog, not because we’re big fans of lists in themselves, we’re providing this link to Tom’s list of “Top 10 technical writing trend predictions for 2015.”

We’re not going to start down the “list trail” – it’s too far into 2016 for that. But Tom’s list is likely to be as insightful as any and can be expected to carry you well into 2016.

He leads off with “More authoring tools and CMSs accept Markdown”. See, this is really technical stuff, but it’s likely to be of help or interest to tech writing practitioners so we’re passing it along. – Doug Bedell

Clarity In Progress

Posted on January 31, 2016
Filed Under Business, Communication, Technology, The Writing Life | Leave a Comment

Who would disagree that the biggest issue in technical writing “is the inability to see simplicity in complexity.” If you’re trying to reach even a veteran engineer with guidance or instructions on a new procedure or process, you want to be as direct as the process allows.

We thank Mark Crawford on the ASME.org site for discussing this question of simplicity in complexity via his “How Engineers Can Improve Technical Writing” post. It’s been out there a few years now but, as we suspect may be true of other colleagues, we’ve just caught up with it in the Internet’s vastness.

To write with clarity and directness requires that you understand a technical situation as fully as your capacities allow. We assume you wouldn’t be writing about such challenging material if you weren’t qualified to do so. The issue isn’t technical competence so much as communication prowess. You need to describe a process clearly and competently. When you think you’ve finished, the test is, Have you communicated well?

“After all,” Crawford adds, “technical writing is not just about language skills – it’s about how we think.” Indeed. Clear writing requires clear thinking. And that’s as much a communication issue as a technical one. You can’t communicate well if your thinking is garbled at the gate.

So before plunging into a process, take time to review it first. What is it intended to accomplish? How can a reader/user get there promptly, clearly and safely? Simple sounding, yes, but not so simple in practice. Often we’re too rushed, or feel so, to
organize, settle down and produce a clearly described series of steps to get there as intended. – Doug Bedell

Instructions As Music Rather Than Noise

Posted on January 19, 2016
Filed Under Communication, Technology | Leave a Comment

Effective technical writing (as all forms of writing) begins with the desire, and ability, to communicate well. What’s that mean in the technical realm? As always, to be focused, first of all, on your audience. Who will be using, and hopefully consuming, your writing, in the form of instructions, plans and aims? Do they have infinite patience? Probably not.

Your readers are more likely to be people in something of a hurry to use the instructions at hand to get to a desired end. It’s the end, not the instructions for getting there, that matters most. Sure, they shouldn’t be hurried. But if instructions or explanations don’t produce a prompt result, your readers are likely to feel harried rather than engaged. Your call on which is the more likely.

Let’s turn to an example from outside the technical realm – listening to music. At a concert, a listener’s aim is, hopefully, to be elevated by a performance. (In a technical setting, it’s to be satisfied with an outcome.) What does the concert goer have at hand to be ready for an inspiring experience. Most likely, the program. It functions as a sort of technical manual for the occasion, at least an introductory one.

“Programs,” writes Aarik Danielsen in the Columbia, Missouri, Daily Tribune, ” are helpful guides to the repertoire about to be performed; sometimes they include revealing program notes about composers and their muses.

“But,” he adds, “they also tend to include a great deal of fine technical details that wow the initiated but otherwise read like a foreign language. There are often dry lists of performers’ credits and educational achievements…” Such “resumes,” as Aarik calls them, “are meant to establish a pedigree but can up the intimidation factor for audience members.” So avoid them, they’re not necessary to the end in view – enjoyment of a concert, or in a technical setting, accomplishment of a task.

“Often, a concert program,” Danielsen warns, “reads like something written by the academy for the elite, with little to offer by way of illumination for the ‘common’ listener.”

So consider whether the technical writing you’re embarking on will be music to a user’s ears, or a passport to a jarring jungle of details. The difference is readily within a good writer’s ability to discern and correct, as appropriate. One will be satisfying music, and the other, more like annoying noise. – Doug Bedell

From Off the Shelf Onto a Screen

Posted on December 9, 2015
Filed Under Communication, Technology | Leave a Comment

The annals of TC World hold a piece that we enjoying coming back to, as a reminder of the noble lineage of technical communication and how it’s been developing into the digital age. End-users have always needed guidance materials, but now they’re using them in an ever-more screen-centered, collaborative environment.

“A technical writer,” Monalisa Sen and Debarshi Gupta Biswas note, “has truly become ‘an honest mediator between people who create technology and who use technology.'”

And the print industry has lost its exclusive hold over technical materials. “The demand of the day was mobility, optimum use of digital space, and accessibility. Most of these were lacking in a user manual, which now became a product best suited for a bookshelf.” And they provide an evolutionary table of the craft’s development.

The broad application of technical materials, of course, depends on the industry you’re in, and how specialized its requirements are. But the crisp style, formatting and ready accessibility of operational material is applicable everywhere.

You turn to a technical manual, or sheet of instructions, for guidance – clear, tested instructions – on how to to something safely and efficiently. That’s a noble aim for any kind of writing, but it’s imperative in a technical context.

Shaping the nature of today’s technical materials, Sen and Biswas note, is the pervasive nature of their transmission, through such means as YouTube, on-screen texts and other means of digital formatting.

“An analysis of the emerging technologies,” they conclude, “suggests that software products in the future will have well-designed and intuitive user interfaces, with a reduced need for detailed reference manuals but crisp on-screen instructions to facilitate transfer of information to the users.” And text-intensive formats will decline.

So if you want to be in the forefront of the field, think about how information is best displayed digitally and without turning page-after-page. No great revelation, but certainly the trend of our increasingly screen-centered times. – Doug Bedell

« go back — keep looking »

An Awesome Web Community

Economics Without Weeds

Getting ‘Out There’ Matters Greatly

Bless Her, Sarah’s All For Sharing

Improving Toward a Summit – a Constant Process

Technical Writing Is Like Other Writing Done Well

A 2016 List From Tom Johnson

Clarity In Progress

Instructions As Music Rather Than Noise

From Off the Shelf Onto a Screen

Recently

Categories

Archives

Blogroll

Find It