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.

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

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)

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)

Storyboards for Technicians

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

Technical Writing’s About Reality

Recently

Categories

Archives

Blogroll

Find It