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.

A Versatile Writer, Based on a Boat

Posted on September 5, 2013
Filed Under Technology, The Writing Life | Leave a Comment

Now here’s a technical writing colleague we might all want to emulate!  Remember John D. McDonald’s Travis McGee novels, in which the detective hero lived on a houseboat, The Busted Flush (named after a poker hand he won)  in 1960s Florida? Well, meet William Hutchinson, a sure enough technical writer based in Redondo Beach, California, who lives  on his boat in the harbor there.

52140f3ac27a9.preview-300Hutchinson started writing fiction as a respite from the “dryness” of technical writing. “Technical writing is a lot more exact and it’s a lot more dry,” he says, “You don’t get the creativity so I started writing this book, “Sigma One,” right after the Soviets and the U.S. came to an arms agreement. I hypothesized why that might have happened in spite of what was in the press…”

You don’t hypothesize, of course, in technical writing. But however you get  your writing juices flowing, and it may take a while, they might just stream away. It’s nice to have an alternative channel for more creative stuff. Hutchinson is to be envied in that respect. He has a discipline,  and attempts to write two or three fictional pages a day. He’s a movie fan who tends to think in pictures and writes what he sees in his mind. Again, that’s on his imaginative, not so much technical, side.

Not surprisingly, technical writing comes easier for Hutchinson than creative writing, and not only because he’s spent all those years as a systems engineer. “The hardest part of creative writing,” he says, “is getting the conversations correct and getting in(to) the head of the characters.” In technical writing, it’s describe it as it is, with no head games.

We salute a truly versatile technical writing colleague out there on the West Coast! – Doug Bedell

(Photo of William Hutchinson from The Beach Reporter, The Beach Cities, CA)

Subheads for Clarity, If not Beauty

Posted on August 30, 2013
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Technical writing needs to be orderly, but to insure that it’s read and understood by busy people, it definitely shouldn’t be dense. Aside from writing reasonably short, orderly sentences, adding subheads when the focus changes a bit is a mechanical, but very helpful, way of keeping a reader with you. Subheads are perhaps a tech writer’s most valuable organizational tool.

imagesTom Johnson, on his excellent “I’d Rather Be Writing” technical writing blog, deals with the virtues of subheads at some depth. Tom took a poll on why “users can’t find answers in help material.”  And he found that “help is either too long so users can’t find the answer, or help is too short so users can’t find the answer.” So what’s needed is a mechanism to facilitate organizing and scanning a page. (Oh, there’s that “f” word again.) Subheads are the answer both to orderly writing and orderly page layout.

Use subheads, first, to organize material that belongs together and then to draw your reader’s eyes to your handiwork. You’ve made his or her day when it’s easy to follow what you’re presenting. Subheads along with reasonably clear writing are the answer.  They’re both attractive  typographically and  highly utilitarian. (Below a subhead, or instead of one, a “bullet” dot to set off key sentences or paragraphs can also be helpful.)

A maximum of four indented subheads on a page, as illustrated here, may actually be too many, unless your material is so complex that it requires them. Definitely avoid run-on subheads, as much as run-on writing. The idea is to be organized, not typographically lush. Typographical techniques aren’t a substitute for clear, well-organized writing, just helpmates in negotiating your terrain. The eye can be distracted by too many of them.

“Almost any Wikipedia page provides a great example of subheadings in action,” Tom notes. “There we have many paragraphs of content broken up by subheadings, with a built-in navigation embedded at the top. It’s a model that seems to work well on the web.” Subheads work well on paper, too, if they’re not overdone. Keep them always in mind as your technical writing unfolds. – Doug Bedell 

Apostrophes Matter When You’re Claiming to be Careful

Posted on August 2, 2013
Filed Under Business, The Writing Life | Leave a Comment

Geez, we don’t want to be sticklers for detail, but in technical writing, detail’s important – especially when you’re claiming to pay attention to it, as is the case with this MacPrices.net post, “iFixit Announces Free Tech Writing Handbook.” We were surfing for an Insights topic when we came across this post and its declaration that “I only hire applicants who practice good grammar.”

macfixittwhWe’re not sure that punctuation is necessarily included in “good grammar,” but sloppy punctuation derails readers as easily as sloppy grammar.  And we found a half-dozen punctuation errors and a couple of other writing sins in this post by iFixit CEO Kyle Wiens:

First, in the opening sentence, there’s a semantic miscue – “I kicked up a bit of a dust last year…” (italics added) “I kicked up a bit of dust…” is correct, of course.  Then, in the next sentence, an apostrophe is omitted in “an applicants attention to detail.” (Even WordPress has this underscored.) And there are several other instances in which apostrophes are omitted.

Then there’s a space lacking where there ought to be a dash, so we have “We teach real people how to do real-world thingshow to repair computers…” (Again, WordPress is on the ball.)

In the sixth paragraph, we have quote marks missing around the sentences beginning “I’m sorry…”  And this paragraph ends simply, “My bad.” “My bad” what?

We may be coming across as quibblers. But when a technical writing colleague posts on his book being “a useful resource for anyone looking to improve basic writing skills,” careful proofreading is such a skill, even in, or especially in, a web promotional release.  – Doug Bedell

‘Twitter Thinking’ in Tech Writing

Posted on July 26, 2013
Filed Under Communication, Technology, The Writing Life | Leave a Comment

imgresMy Encore colleague (and proprietor), Dennis Owen, has come up with a neat concept to trim up technical writing – apply a little “Twitter technique” to documentation. Twitter on documents? Come on…but wait, what’s he getting at?

“Yesterday I was editing a procedure from one of my colleagues (at a company Dennis is currently working at) and he had some bullets in a long list of an organization’s responsibilities, like:

Some might say this is  trim enough. But wait, if we give the list a “Twitter touch,” here’s what Dennis suggests it might look like:

This is what an old city editor of mine would have called “tight writing,” and it’s a definite improvement in reading efficiency. But who has a city editor anymore? Instead, a Twitter-like technique is worth keeping in mind. Yes, a character count, figuratively speaking. There are 129 characters (or so) in the first list and 62 (or so) in the second. Both are within Twitter’s 140-character limit, but which is more efficient to read, and probably remember? Clearly, the second.

We’re not recommending that you count the characters in everything you write – that would be daunting. But if you picture yourself as tweeting, rather than merely writing, maybe my old city editor enters your ken, and that would be a blessing, indeed!  Over time, your writing will be immeasurably improved – that is, will become clearer and more efficient to read.

So, the next time you tackle a technical document, get up there on a power line and tweet on! Your writing and, your readers’ grasp of  whatever procedure is involved, will be energized. Truly. – Doug Bedell

Hey, Techie, Pretend You’re On Twitter Posting Clearly

Posted on July 1, 2013
Filed Under Communication, Technology, The Writing Life | Leave a Comment

Gee, it occurs to us that the same approach can be used for technical writing that’s recommended in this Business2Community blog post for social media writing. Really? Sure. We’re not talking about the quirky, abbreviated style of social media writing, just simple, straight-out expression.

images“Writing in plain English,” the post begins, “means writing in a simple and straightforward manner that lets you reach the widest possible audience.” With technical writing, of course, you’re not necessarily trying to reach a particularly wide audience (unless you’re writing a computer manual), but you want to “avoid technical jargon…”  anyway. You’ll likely need to be using specialized vocabulary, but  good writing is good writing, wherever it’s found – clear, direct, and usually to the point.

Bear in mind that, while writing for social media is thought of as aimed at the youngest device owners, “older” can, in fact, be anyone over 30. They weren’t brought up or trained  on abbreviations and foreshortened words and expressions.

There’s not a whole lot of difference between writing for the general public and for users of technical manuals or instructions. We’re all humans who appreciate being taken seriously. Should you be too casual with language, B2C notes, “People may conclude that you are equally casual with your customer service or quality control.”  There it is – technical writing equated with customer service! An appropriate pairing, indeed.

Writing concisely, Brian Scott, the B2C writer, notes doesn’t mean turning out hamburger. His direct, perfectly acceptable alternative (real words) sentence for a Twitter tweet has only 81 characters. It’s not necessary to play “stump (or entangle) the reader,” online or off, after all.

It’s certainly possible that social media writing can become too breezy for its own good, but so far, it’s really quite functional. So is the best technical writing. Remember that the next time you’re scanning Facebook before turning to your day’s paid writing rounds. – Doug Bedell 

To Ancient Rome, and Hollywood Glory, in a Lunch Hour

Posted on June 18, 2013
Filed Under Technology, The Writing Life | Leave a Comment

Watch what you’re doing on your lunch hour – consider it, even, a time of imaginative opportunity. James Erwin, a technical writer in Des Moines, Iowa, decided on one of his lunch hours awhile back to respond to a question he’d seen on the Reddit social networking site: “Could a battalion of U.S. marines, transported back in time, destroy the entire Roman Empire?”

imageErwin started to draft a story outline on his lunch hour. By the time his break was up, he’d posted eight pages of a story he entitled “Rome Sweet Rome.” It kind of went viral. By the time he got home from work that day, Erwin’s outline had had 250,000 readers, and he had a contact from a talent management firm in Los Angeles that liked his concept – “the diary of a U.S. marine whose battalion is mysteriously transported from Afghanistan to ancient Rome.”

Now, two years later, a movie script for “Rome Sweet Rome” is almost done and ready to be sent to a movie production company. Ah, creativity! You never know when the muse will alight in your consciousness! In Erwin’s case, it was after he’d completed thousands of pages of technical manuals and related writing over a 10-year “apprenticeship.” Now he’s a budding screenwriter, receiving checks that are too big, apparently, to talk about. And he’s back to his old technical writing rounds with a greatly enhanced sense of how one’s imagination can be sparked by an oddball inspiration.

Erwin attributes his evident screenwriting success, at least this once, to the gritty routine of technical writing. “I think” he reflects “(that) just having that sort of apprenticeship and the ability to sit down, block things out and just start typing, I couldn’t have put out eight pages in an hour and I certainly couldn’t have possibly written a screenplay three months later without that.”

So, while you may “only” be writing a procedure  for operating one sort of pump or another, be ever mindful that what you’re doing can lead to somewhere greater – like the gates of ancient Rome. Especially these days, when your writing skill can spark a virtually instant Internet reception. – Doug Bedell

When Twirling a Yo-Yo Becomes an Art

Posted on May 7, 2013
Filed Under Communication, The Writing Life | Leave a Comment

Here’s a young man we know nothing about except that his name is Black, just that, and can he handle a yo-yo! First one yo-yo, then two of them together. He’s thrilled a TED audience and, now us, watching that performance. So what’s there about a yo-yo that’s so awesome? It’s not the yo-yo itself, two half spheres with a string tied around their axis peg. (At least that’s how my yo-yo was set up when I was a kid.) It’s the skill that brings it the level demonstrated by Black, who’s  twice become a world yo-yo champion.

imagesSkill honed by dedication. That’s at the heart of any craft mastery. At 14, Black got a yo-yo, discovered he enjoyed twirling it and, 10,000 hours of practice later, became a world yo-yo champion. Now he brings the TED audience to its feet demonstrating his skill in handling two yo-yos at once.

Trivial? Maybe twirling a yo-yo, sending it “round the world” or putting it to “sleep” like I did as a kid, is pretty trivial. (Dennis Owen recalls “walking the dog” and “rocking the cradle” as well.) But whatever you’re doing, sufficient practice at perfecting technique can bring it all the way to the level of art. You’ve got the interest, or you wouldn’t be doing that much practicing. So toning up the brain and muscles to be a champion at whatever enthralls you  becomes the challenge.

Watch Black whisk a cloth from beneath a vase of flowers with his yo-yo. Admire his total setting, which is stagecraft along with yo-yo twirling. Note how he keeps the Ted audience intent on what he’s doing. Altogether, it’s spell-binding. That’s what 10,000 hours of practice did for one young man with a couple of yo-yos and the will to wield them well, very well indeed.  – Doug Bedell

Technical Writing in Shorter ‘Page Bursts’

Posted on April 5, 2013
Filed Under Communication, Technology, The Writing Life | Leave a Comment

With the Web being such a factor in communication now, it’s bound to be affecting where people turn for information, even technical information. “Web consults” are likely to be increasingly one’s first choice on where to look for information, of whatever degree of complexity. While this doesn’t apply as much to site-specific information, it’s likely to be influencing the formatting of technical writing, wherever it may be aimed.

headshot-231x300In this context, we’ve come across a blog, “Home of the Ryan,” a new blog whose writer, Ryan Pollack, has been in technical writing for nine years or so. He refers us to the blog “Every Page is Page One,” and that’s been an especially welcome discovery. This site’s proprietor, Mark Baker (shown here), has had 25 years in technical communication, including on the Web.

Baker seems to be saying that technical information is increasingly being formatted in short bursts, or page views. One doesn’t reach for an entire manual any longer so much as turn to the Web to find the topic or situation he or she needs help with. This depends partly on where you’re working, of course, but web-formatted materials are coming increasingly into use.

Information can be obtained more efficiently this way and thinking in terms of web pages rather than entire manuals has pertinent advantages. We’ll have to peruse further the implications of “every page being page one.” They have a lot to do with whether or not your technical writing is actually being posted on the Web. Increasingly, that’s likely to be so. Or maybe not. You wouldn’t want Google ushering people through sensitive areas of your plant.

Either way, the reality is that web formatting will increasingly be influencing formatting of all sorts. This means it’s likely to be shorter and crisper than before. And that’s a gain, if also something of a hazard when complexity arises.

Whatever your situation, here are two more places to hang around – “Home of the Ryan,” and “Every Page is Page One” – to get the feel of these new settings for technical communication. – Doug Bedell

What’s to be Read, With So Much to Read?

Posted on March 12, 2013
Filed Under Communication, Technology, The Writing Life | Leave a Comment

books-248x300Reading is important to writing, no less so if you’re a technical writer. Broad horizons and readiness of expression at whatever you write are greatly abetted by regular, indeed relentless, reading.

It’s getting easier, and less expensive, than ever to become a self-priming reader. I, for example, have 30 either great or useful books on my iPad’s Kindle reader. From the Kindle store, they cost half, or less, than their hardbound price, and they can be underlined or annotated as though they have paper pages. I don’t know, for example, a bookstore at which I could have picked up William Zinsser’s “The Writer Who Stayed,” but it was available in an instant from the Kindle store. (Zinsser as a younger man and a writer for the New York Herald Tribune, knew my dad as a bank manager on Times Square and, when I was in high school, submitted for me a letter to the editor I had written that the Tribune published. This is meant not as any sort of disclaimer, but simply a formative memory.)

So as a regular writer (though in short, web-based takes), I was just a bit ago pleased to note consultant Kevin Eikenberry’s blog post on “Why You Should Read More Broadly and How to Do It”. Almost as I was just saying he writes, “Today there is far more quantity of reading materials (in more formats) available than ever before, and perhaps because of the proliferation and niche-ification (I know, I made up the word) of those materials, we read differently.”

One used to read mainly the classics. Today, Eikenberry notes, there’s a lot to read just in occupational categories and readers “would be hard pressed to keep up just in the strategy, leadership, management, change (or pick your sub genre) area alone.” So if you want to be a fully effective person nowadays, what’s to be read among all the choices available?

Eikenberry suggests several “food groups to add to what might be a bland, unbalanced and unhealthy personal reading menu.” Read fiction, he urges, “it gives your mind a break…” Read a classic, too, something you’ve always want to read, or have known you should. Read older books, “any master of a topic is a student of the past…” (Boy, is that true in these politically impacted times.) Read biographies, read history and read outside your industry. “…reading within your industry or discipline,” Eikenberry feels, “will never create a breakthrough idea.”

And read serendipitously, on the spur of the moment by picking up a new magazine at a newsstand or something a friend recommends. That way, surely, lies discovery, Eikenberry advises.

It all comes down to reading for surprise and self-enhancement. There’s more than ever readily available for profitable perusing, whether you’re in a technical field or not, so get at it, and stay with it. – Doug Bedell

Starting Young at What We Do

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

funny_technical_writer_t_shirts-r6aa6c1a7bb754398a3cb0b2c30107687_f0cj6_512You want to instill goals and ambitions into young people, say, your grandchildren? We thought so. With their aspirations in view (by you, if not yet them), you might want to equip them with this inspirational Zazzle baby’s T-shirt.

We’re not selling them, just referring parent or grandparent Insights readers to a source of inspiration – for your youngsters, and for you, who will be paying their bills. Dennis Owen came up with it, actually. Nothing like inculcating aims and aspirations at the earliest opportunity!

But how do you ascertain that your youngster has promise as a technical writer and not a violinist? Hey, we just handle the writing. Answers to questions like that need to be sought elsewhere. – Doug Bedell

« go back — keep looking »
Email Subscribe

Recently


Categories


Archives


Blogroll