Ready, Write, Aim – No, That’s Not It
Posted on April 8, 2016
Filed Under Communication, The Writing Life | Leave a Comment
What’s the most important element in starting a technical writing task? (Or any other, for that matter.) Why, it’s your aim, of course. “What am I trying to accomplish with this? Where are we headed?” Putting first things first requires that you have a good fix on what you’re aiming for before you start doing it.
Don’t be the kind of writer who just tries to fill space – that won’t have a worthwhile outcome. We used to do editorial writing, with a wide column of empty space to be filled daily. But filling that space wasn’t, or shouldn’t have been, our aim. Having something to say was what benefitted readers, sharpened their perceptions and expectations of us. That was, or should have been, our real aim.
Such thoughts occurred (again) while reading Neal Caplan’s post “…You’re Not Good Enough.” Being judged by other people’s standards is okay, so long as you all have the same aim. But if you don’t, watch out. You may get to where they’re headed and find, pretty quickly, that it’s not where you need to be. It’s all in your aim.
Taking careful aim shouldn’t be any different for technical writers than anyone else. What in the way of writing crisp, efficient documentation should be your intent on behalf of those who will be using it? Don’t just start spieling out directions. They may get pretty roundabout.
“As nice as it is to hold a copy of a book that you wrote,” Neal notes, “it’s not so nice to tell your customers that they MUST read that book before they can use your product. Or, more likely, that shelf full of books. This is the opposite of ‘just in time’ help: it’s ‘become an expert on this product before you ever think about touching the UI.’”
Your aim isn’t to help colleagues become expert at what you’re doing, but to become better at what they’re trying to accomplish. There’s always more to discover, learn and know. The real question is: to what end? What are you aiming for, organizationally and individually? Keep focused on that; it’s what matters most. – 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
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
Technical Writers Connect With Needs, Solutions
Posted on November 9, 2015
Filed Under Communication, The Writing Life | Leave a Comment
Technical writers, you’ll be pleased to know, aren’t just scribblers. In their full professional regalia, they’re connectors, too. That’s a point made by Bart D. Leahy on his Heroic Technical Writing blog, which, by the way, has a Superman header. (After all, Clark Kent was a reporter.)
On their rounds, technical writers spot needs or frequently will be introduced to people with special abilities. If they take note of the skills of such specialists, they’ll be in a position to connect them to someone who, further along the way, might be able to consult with them.
Leahy notes that Malcolm Gladwell describes such linkups in his book, The Tipping Point. “Connectors,” says Gladwell, “are the people in a community who know large numbers of people and who are in the habit of making introductions. A connector is essentially the social equivalent of a computer network hub…”
Yes, technical writers often find themselves at the heart of the action. They need to sort through what’s occurring and, in that guise, might well make recommendations on how to improve the situation. In such instances, previously established contacts and accumulated insights are among their assets.
If not supermen, technical writers are knowledge hubs as well as scribes. “If you know what types of things other people know,” Leahy points out, “you can leverage that network when you have a question about certain topics. Or, conversely, if you find something of interest to someone who has particular interests, you can connect them with something or someone of interest to them later.”
So, technical writers are like circuit riders, or knowledge carriers. Don’t ever view them, the likes of Encore’s Dennis Owen, as drudges. That could cost you contacts and solutions. – Doug Bedell
Purdue’s Online Lab: A Good Place to Approach Technical Writing
Posted on October 26, 2015
Filed Under Communication, The Writing Life | Leave a Comment
Purdue University’s Online Writing Lab (OWL) provides virtually an online course in technical writing, free of any “charge” except for rapt attention. “These OWL resources,” says the site, “will help you conduct research and compose documents for the workplace, such as memoranda and business letters. This section also includes resources for writing report and scientific abstracts – pretty close to the definition of technical writing.
This isn’t to say, of course, that simply by scanning Purdue’s online materials you’ll become a practiced technical writer. Practice itself, preceded by an aim and sense of purpose and audience, is virtually the key to effective technical writing. But since technical writing is also orderly writing, Purdue’s Writing Lab, it appears, can be of great start-up help.
Founded as a land-grant college, Purdue evolved into a collegiate powerhouse, and not just in football. In 1891, it “acquired a working railroad engine to mount in a newly established locomotive laboratory. It was one more step in the development of Purdue as one of the world’s leaders in engineering teaching and research.”
So spend some time at Purdue’s Online Writing Lab. There’s a proud academic tradition behind it, a polished working-level, technically astute view of the world. On Boilermakers! – Doug Bedell
As the World Turns, So Does Our ‘Beat’
Posted on September 29, 2015
Filed Under Communication, Technology, The Writing Life | Leave a Comment
A technical writer named Rebecca muses on the web about her choices of employment – and her freedom to make them. That, as we know, is one of the benefits of being a “lone wolf” technical writer.
“My long-term goal in becoming a technical communicator,” Rebecca writes, “is to be an outsourced employee, but without a larger ‘umbrella’ company sending me my W-2’s each year. I want to dictate the companies I work for and have some control over the projects I accept. I am comfortable putting on that ‘company’s uniform’ for a temporary time and then moving on.”
Rebecca quotes R. Stanley Dicks in Digital Literacy for Technical Communication: “Many more technical communicators will be officially unemployed but constantly working. They will be following the consulting/temp agency model that already characterizes the work of many communicators.”
Speaking for herself, Rebecca adds that “I am hoping to open a fortune cookie with just that prediction for my future: “You will soon find yourself unemployed, but always working.”
That’s not a paradox, it’s the work of a consultant, which many technical writers, including Encore’s Dennis Owen, actually are. Their roles are well-suited to an increasingly digital economy in a continuing state of emergence.
Dennis has been something of a pioneer in technical consulting, working in jobs where he’s been needed and can make important contributions, but not working these past few decades in a job. And the varied experiences he has had as a result have been invaluable.
Rebecca expresses something of the same sense of fulfillment: “The technical writing program I was set to enter was very solid and respected. But in 2001, it wasn’t very focused on digital media. Within a few short years, their ‘technical writing’ program became their ‘Technical Communications’ program. It was completely revamped several times over the next few years, as they slowly began to focus the program more on the emerging use of technology.
“Had I enrolled back in 2001,” Rebecca adds, “I would have been ‘getting to the party a little too early’.”
So roll with the opportunities as they arise in a steadily changing world. Like anyone else, actually, that’s what observant technical writers ought to be mindful of in these challenging times. It’s sort of like a newsman’s ‘beat’. – Doug Bedell
When to Pause to ‘Get It Down’?
Posted on September 18, 2015
Filed Under Communication, Technology, The Writing Life | Leave a Comment
Jim Grey on his Stories From the Software Salt Mines site makes a clearcut distinction that’s worth stamping into one’s awareness: “Personal computers are for content creators; mobile devices are for content consumers.” Or, creators – think desktop; consumers – think mobile.
Makes pretty obvious sense – up to a point that seems to be approaching with increasing speed. The continuing development of iPads and other mobile devices tempts us to use them for creating content, not just reading or viewing it. (Apple says that, come November, its newest iPad will have an external keyboard available.)
Technical writers likely are paying increasing attention to these distinctions, or to their increasing tendency to blur together. It would be nice to create serviceable copy wherever you have the ability to pause a bit, not only at your desktop, but, say, in the park. Your insights might well be sharper and your writing fresher. Using a mobile device is like having your brain more readily at hand, providing your fingers have ready access to what you’re thinking.
Mobile devices as “mere” displays allow us to take advantage of idle time. Jim Grey notes that “an Internet device in our pocket lets us pleasantly wile away the minutes we spend waiting — in doctors’ waiting rooms, before meetings begin, in the john.” But he’s not going to start blog posting on his phone.
Unless, we’d venture, Jim or any of us finds ourselves in a situation where it would be advantageous to get our thoughts down coherently because they’re especially important to us or maybe to others.
You see what’s happening here? The modes of expression are tending to merge with the availabilty of technology that can help that happen. Reflections that used to be random meditations can now be recorded musings – if and when we feel they’re significant enough. This can help make us more observant, as well as more reflective, and that’s all to the good, most of the time.
Remember the title of Jim Grey’s blog – “Stories from the Software Salt Mines.” We don’t want to feel that we’re living in a salt mine, just that we have the ability to use a mental pick and shovel when they’re occasionally advisable – for the record, say. Maybe we’d even get more sleep some nights. – Doug Bedell
Progress Promptings From a Roller Coaster
Posted on August 31, 2015
Filed Under Business, Communication, Technology, The Writing Life | Leave a Comment
One of the truly liberating aspects of a talent like technical writing is the ability to function with minimal support and oversight. That’s the setting you’re likely to find at a start-up company, so don’t overlook the advantages of working for a beckoning startup.
Tom Johnson, of I’d Rather Be Writing, asks: “What qualities should technical writers have to work at startups?” He answers by listing: Technical aptitude, Independence and leadership, Content strategy skills, Versatility and Stability.
Stability? Aside from coming to work each day at an agreed time, what’s that mean in terms of successful technical writing?
“To ride the roller coaster of a startup,” Tom explains, “you need to have stability in your career, knowing that if your job dries up you can find another, or that you have savings to cover a period of unemployment during the transition, or that you can handle any changes and continue with the company, perhaps in another role entirely (e.g., support or training manager).”
Actually, as we discovered at a trip to our local, continually-evolving amusement park recently, the roller coaster was among the milder of the thrill rides. You’ve got to be prepared for anything that fate or fortune throw at you these days.
Underlying ability, interest and fortitude still contribute the most to your ability to keep your seat when things get turbulent which, at some point, they most likely will. Close your eyes (for a moment), hold on, circulate, observe and write well. Keep your hands on the car, not up in the air, as the non-achievers tend to do.
Okay, they’re just doing that out of exuberance (or maybe in defiance of fear). But it’s not exuberance that keeps you safely employed at today’s workplaces, or on behalf of today’s clients. It’s ability, vision and diligence. – Doug Bedell
« go back — keep looking »
Recently
- Presentations With Forethought
- Technical Writing’s Lineage – Surely It’s Deeper than Digital
- At the Holidays, Twitting Amazon
- Successful Cookie Baking – From Mom, an Acknowledged Expert
- Slides for a Tech Writer’s Craft
- Digital or Not, Be Clear
- Being Watchful About Digital Designs…
- When Proposals Don’t Click, Keep Making Them Anyway
- Like a Good Gardener, Help an Enterprise Keep Itself Current
- We’re Leaders All, And Need to Think That Way
Categories
Archives
- January 2017
- December 2016
- November 2016
- October 2016
- September 2016
- August 2016
- July 2016
- June 2016
- May 2016
- April 2016
- March 2016
- February 2016
- January 2016
- December 2015
- November 2015
- October 2015
- September 2015
- August 2015
- July 2015
- June 2015
- May 2015
- April 2015
- March 2015
- February 2015
- January 2015
- December 2014
- November 2014
- October 2014
- March 2014
- February 2014
- January 2014
- December 2013
- November 2013
- October 2013
- September 2013
- August 2013
- July 2013
- June 2013
- May 2013
- April 2013
- March 2013
- February 2013
- January 2013
- December 2012
- November 2012
- October 2012
- September 2012
- August 2012
- July 2012
- June 2012
- May 2012
- April 2012
- March 2012
- February 2012
- January 2012
- December 2011
- November 2011
- October 2011
- September 2011
- August 2011
- July 2011
- June 2011
- May 2011
- April 2011
- March 2011
- February 2011
- January 2011
- December 2010
- November 2010
- October 2010
- September 2010
- August 2010
- July 2010
- June 2010
- May 2010
- April 2010
- March 2010
- February 2010
- January 2010