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.

Making Technical Writing Dance May Be Next

Posted on September 30, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

It’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

Comments

Virtual Reality at Elevator Doors? – Indeed So

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

Looking 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

Comments

Cruising Clearly Through a Product or Process

Posted on September 8, 2016
Filed Under Communication, Technology, Uncategorized | Leave a Comment

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

Comments

Storyboards for Technicians

Posted on August 26, 2016
Filed Under Communication, Technology | Leave a Comment

Pictures can “tell a thousand words,” or at least a snapshot’s worth. Why not consider including them as part of a written technical procedure or manual? Greg Larson on the TechWhirl blog provides inspiration for doing just that.

Greg suggests both pictures and sounds. But to keep the result from becoming a confusing garble, he advises planning it carefully in advance – how else but with storyboards? “Storyboards,” he writes, help you organize before you begin to develop your presentation, video tutorial, animation, simulation or web-based training, by putting it into a format that allows others to see the sequence of your presentation before you begin production.

“It helps organize the pile (or the idea that could become a pile) of videos, photos, audio clips, and documents according to a logical sequence that can be aligned with text or audio.”

You might not be planning that ambitious an audio-visual presentation, but laying out pages in advance, what newspaper and magazine editors have always done, will insure a more coherent, informative result. Technical writing, illustrated or not, always has to lead to a safe, effective endpoint. We’d say “conclusion,” but this, after all, involves procedures, not novels. And procedures can bring primal results.

For technicians, being resourceful never includes being casual. A display of photos in a procedure or manual has to be appropriate to the end result – carefully chosen, thought through and illustrative of the process involved. No comics allowed!

“Storyboards,” Larson explains, “help you organize before you begin to develop your presentation, video tutorial, animation, simulation or web-based training, by putting it into a format that allows others to see the sequence of your presentation before you begin production. It helps organize the pile (or the idea that could become a pile) of videos, photos, audio clips, and documents according to a logical sequence that can be aligned with text or audio.”

So pile it on, friends, but carefully. – Doug Bedell

Comments

Writing Clearly About Documentation Can Be Done – Of Course It Can

Posted on August 17, 2016
Filed Under Technology, The Writing Life | Leave a Comment

“Give every person his or her due” – a prime precept, if there ever was one. Why are we noting it here? Because Neal Kaplan on the Customers and Content blog warns about a couple of dangerous myths, a caution we second – that “programmers can’t write and writers can’t code.”

That’s pigeon-holing people when we should be thinking of eagles flying high. In this new digital age, people need to be recognizing complementary skills and developing them to the best of their abilities – human abilities, which can span categories.

Citing an article that got under his skin, “Why Developers Write Horrible Documentation,” Kaplan faults its writer for thinking in terms of generalizations, a hazard to be sure.

The particulars of the matter come down to what a given technical writer accomplishes both in terms of programming and explaining it well. It can be done. And it needs to be done more and more often.

Supposedly, developers get too close to a product. Well, did Herman Melville get too close to whales in producing Moby Dick? Of course not.

Developers can create a usable product, but they can’t be trusted to write the documentation? “Here’s the thing,” Kaplan explains. “maybe no one taught the developers about product docs, about what works and what does(n’t), about what their users are looking for.”

But they can learn – as Kaplan explains, he himself did. Complexity requires insight to get on better terms with understanding. Learning, rather than harpooning.

Lest we be accused of mixing eagles with whales, we’d best make the clear point that what comes out of a workplace is forecast by how relational and cooperative its denizens are.

Tasks clearly understood are likely to be tasks performed well. That’s a principle for technical writers and their colleagues to honor. – Doug Bedell
(Photo via Pinterest)

Comments

Technical Writing’s About Reality

Posted on August 10, 2016
Filed Under Business, Technology, The Writing Life | Leave a Comment

So what’s the most important trait of a technical writer?

Sharon Burton answers, no surprise here, that “I can teach someone to write. I can give them the Good Writing Guidelines, I can set up a structure that they need to follow to create topics. I can teach the basics of any tool we choose. I can teach them about audience and what the audience needs and how that impacts us.

“What I can’t teach is the curiosity to ask questions, to poke at the product, to constantly ask ‘What if…?'” If you consider a technical writer to be an investigator, not merely a writer, as you should, the capacity to inquire and discover is his or her paramount skill. After all, the procedures produced have to be on-the-mark in a highly utilitarian way.

A technical writer has to be sure that he or she is describing reality as it exists and curiosity is necessary to insure that reality has been captured accurately, safely and unfailingly in words for others to follow. Technical writing is good, faithful guidance.

“Non-curious means you just want to format information other people give you,” Sharon Burton writes. And that’s not going to help anyone, least of all your users.”

So be sure you accept that technical writers produce ever-reliable information for path-finding, hard information about step-by-step reality. That’s it, folks. – Doug Bedell
(Image – TechWhirl.com)

Comments

Technical Writing Defined as a Challenging Task

Posted on July 27, 2016
Filed Under Communication, Technology | Leave a Comment

Technical writing is part of the broader field of technical communications – and what, precisely, is that?

Well, TechWirl explains that technical writing is “a field within business communications (that) encompasses a range of disciplines that work together to communicate complex information to those who need it to accomplish a defined task or goal.”

That’s a bit of a mouthful. Technical writing comes down to communicating technical information to those who need it to accomplish something challenging to them or their colleagues.

Yes, technical writing isn’t merely writing and it’s not simply instructions – it’s directional information for getting something done in a challenging context, an assignment that typically requires step-by-step instructions.

Consider technical writing as like producing a guidebook, or at least a pamphlet, with information on getting something challenging accomplished safely and satisfactorily. It’s not simply calling on a muse, a goddess presiding over a particular art, as the dictionary puts it, but providing a pathway to safe, efficient accomplishment.

Sort of like the directions for negotiating a yellow brick road, you might say, if you’re feeling a little lighthearted as you sit down to lead the way to the Emerald City. – Doug Bedell

Photo via Pinterest

Comments

Curiosity: A Reminder Of Ever-Present Opportunity

Posted on July 18, 2016
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Here’s a timeless technical writing post that we’ve kept in our folder and, in a summer lull, consider highly appropriate to share on a blog that aims to promote excellence in technical writing.

Sharon Burton posted it in June, 2014 under the heading, “The most important trait of a technical writer.” What do you think that would be?

Let Sharon answer: “I can teach someone to write. I can give them the Good Writing Guidelines, I can set up a structure that they need to follow to create topics. I can teach the basics of any tool we choose. I can teach them about audience and what the audience needs and how that impacts us.

“What I can’t teach is the curiosity to ask questions, to poke at the product, to constantly ask “What if…?”

There it is, “Curiosity to ask questions…” Why be curious when you’re writing about something that already exists, a process or product that requires a procedure? Because nothing is ever fully finished, complete, beyond evolving a little or a lot, beyond posing a risk of misuse or misunderstanding.

These latter categories are a technical writer’s great opportunity – to promote evolution and to ehhance safety and utility. “Nothing is ever fully finished” – therein lies great opportunity or, at the least, relief from carefully practiced, workaday routine.

Every topic or procedure a technical writer approaches ought to be treated as a learning opportunity with a paramount aim – freshness, newness, a better way of proceeding.

“If you’re curious,” Sharon advises, “you’ll learn more about your tools. You’ll ask more about your audience. You’ll think to ask important questions about the product you’re documenting. You’re thinking about everything as you do it, to understand more deeply everything you work with.”

Yes, technical writing is a form of exploration. You need to know the territory before you can bind it for others to follow safely and efficiently. So don’t ever leave unanswered a question that you or others raise – that might keep you from discovering something additionally important, something that needs to be included for completeness.

We’re glad we held on to Sharon Burton’s ever-pertinent reflections to this summer day when not much is, or seems to be, happening. – Doug Bedell

Comments

No ‘Catch-Up’ Practiced Here

Posted on July 8, 2016
Filed Under Uncategorized | Leave a Comment

Yes, technical writing can be a stressful trade. “No one likes being told what to do,” Anne Gentle writes on JustWriteClic.com. Well, yes and no. Employees subject to the dictate of technical procedures may realize that it’s they’re job to pay them heed, but may also be subject to other pressures to get their tasks done and put the rule book back in the drawer.

So tech writers need to develop a mindset in which they are both public relations people (in the best sense of “relational”) and rule-makers in terms of explaining how safely and efficiently to get things done in challenging settings.

That’s no narrow charter – being kind and promoting accountability at the same time. Timeliness is part of the answer. Colleagues will pay greater heed to information when it reaches them in a timely manner. For one thing, that makes it fresher all around.

“When a bit of code changes that makes a difference in the docs,” Anne writes, “that’s a crucial moment for influencing a particular behavior. The behavior we want to see is writing documentation while the code is fresh in your mind.” Code or any other pertinent change in a safety, procedural or security change in a workplace setting, we’d add.

Don’t wait to be helpful (we’d hesitate to say “directive”) – get the new word out as promptly as possible.

Striking while the “digital” iron is hot is what’s involved here. When people feel they’re being informed in a timely manner, they’re likely to act in a more prudent, compliant manner. The alternate is risking having them act hastily, with material that feels like playing catch-up.

No one in a workplace or at a website that needs technical writers in the first place should want to instill encourage playing “catch-up”. That’s what Anne Gentle has inspired us to advise. – Doug Bedell

Comments

Don’t Fret Over Procedures That Flit By

Posted on June 28, 2016
Filed Under Business, Technology, The Writing Life | Leave a Comment

Just when you thought you’ve gotten into a groove in technical writing – crisp, informative sentences and paragraphs – comes a post proclaiming that s&p’s aren’t really the setting that matters any longer.

Yes, you’ve now got to learn video, 3D and other animated forms of advice giving, says IAM Consultants, Ltd. in Lithuania. (Go to their page on “New trends in technical writing.”)

The “second major trend” says IAM (the first is producing text in downloadable copies), “is that users easily accept visual rather than text type information. Assembly instructions, operational manuals, software interfaces everything is now rather to be explained in video or 3D rotatable objects than text…”

Does Disney have a technical writing branch? That might be worth checking out.

Seriously, making instructional matter as engaging as possible is a worthy goal. But the age of text hasn’t ended, hardly. It’s being amplified, perhaps, by appealing videos, but there’s still no substitute for clear, cogently presented text and diagrams.

We need here to make a distinction between technical writing as instructional material for consumer products and procedural guidance in factories and other actual production settings – writing about processes and procedures. Alertly maintained processes won’t wait for video depictions to keep them current. But a useful guideline always remains – there’s no substitute for clear, cogent presentation, whether “animated” or not.

So be ever mindful of your writing and drafting skills and keep polishing them – static words and diagrams remain with us, and always will, even as recorded images flit by. You can’t underline a video, after all. (Or can you?) – Doug Bedell

Making Technical Writing Dance May Be Next

Comments

Virtual Reality at Elevator Doors? – Indeed So

Comments

Cruising Clearly Through a Product or Process

Comments

Storyboards for Technicians

Comments

Writing Clearly About Documentation Can Be Done – Of Course It Can

Comments

Technical Writing’s About Reality

Comments

Technical Writing Defined as a Challenging Task

Comments

Curiosity: A Reminder Of Ever-Present Opportunity

Comments

No ‘Catch-Up’ Practiced Here

Comments

Don’t Fret Over Procedures That Flit By

Comments

Recently

Categories

Archives

Blogroll

Find It