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.

Pinterest for Tech Writers? You Bet!

Posted on October 1, 2013
Filed Under Business, Communication, Technology | Leave a Comment

It might seem counterintuitive to link Pinterest – the pinboard Web app you tend to associate with garden parties and interior decorating – with technical writing. But that’s wrong. Witness the marvelous job Ugur Akinci has done on Pinterest with his technical writing pinboard. In addition to being a Fortune 100 technical writer, Ugur is an online course designer, a lover of Bossa Nova, running, singing in harmony, positive thinking and meditation. A real renaissance man in a Web setting!

Ugur has a couple of dozen other pinboards besides the one on technical writing. Pinterest ought to be using him as a demonstration of the range of its engaging technology. Everything from Films of Cary Grant tp Technical Communication. And Ugur keeps on servicing them all; he seems particularly in love with Hawaii.

We wonder how today’s Web men and women have time for all the surfing, designing and posting they do, and still maintain their sponsoring discipline, in this case technical writing. It’s an expressive medium, to be sure, but there’s usually not a copydesk rimmed with green-eyeshaded proofreader/headline writers to help with it. We note that Ugur is a PhD, which doubtless has something to do with his capacity for productive creativity. A lot of it has to do with thinking through your aims and concepts beforehand.

Anyhow, Pinterest is a delightful means of portraying your interests on the Web, and thereby doing yourself – whether you’re a technical writer, sprinter or a homemaker – a celebratory service. – Doug Bedell

Comments

Persistence Rewarded M.J. Hurley

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

Dennis Owen and I admire greatly M.J. Hurley, a technical writer whose accomplishments we read about in a Washington Post column by Thomas Heath. M.J. has built a technical writing business that earns her $400,000 annually. She did it through persistence and inspired toil, inherited from her mother, who was killed when she walked into a robbery at a 7-Eleven store in North Carolina 38 years ago.

After teaching and working on her PhD, M.J. decided to go into technical writing and landed her first contract at PPD, a pharmaceutical company in Wilmington, N.C. She landed that work out of sheer tenacity. “I called anyone at PPD who would listen to me,” M.J. recalled. She finally got a contract that “included teaching all new PPD employees to write internal documents.” One of the women at PPD took her aside and told her she wasn’t charging enough, so she upped her rate, in light of the value her technical writing services were adding to the company’s functioning.

“I don’t teach grammar,” M.J. says, “I teach critical thinking. You always have to think about the point you are making. Whether you are writing a user manual, an engineering report or telling your boss what you accomplished on a trip, you have to remember what you are trying to accomplish. You are writing for the customer, not for the person next to you in the pod.”

That’s the aim of any good writing – its impact in the context of its intended use. Technical writers, like any other writers, need appropriately high horizons. M.J. is in demand by managers “who find themselves spending too much time rewriting the reports handed in by their staffers.”

That registers with Dennis. “I basically got my start as a technical writer,” he recalls, “when one of the managers I worked for in Idaho noticed I could write and started giving me reports from other engineers to fix so he didn’t have to. That seems like eons ago.”

“My favorite all-time edit (I’ll never forget it),” Dennis adds, “was when an engineer was writing about a calculation and instead of writing ‘multiply the value by six,’ he wrote ‘the value is augmented by a multiplicative factor of six’…I love that.”

M.J.’s work and the recognition it’s been receiving, Dennis notes, “illustrates how valuable good, concise writing is to a company.” It surely does. – Doug Bedell

(Photo of M.J. Hurley)

Comments

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.

Hutchinson 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)

Comments

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.

Tom 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

Comments

An Engaging Robot’s Emerging from the Internet’s Plastic ‘Sands’

Posted on August 18, 2013
Filed Under Technology | Leave a Comment

When you first see the upper “body” of the InMoov robot that will be demonstrated at the World Maker Faire show in New York’s Queens County next month, your impulse is to exclaim, “Frankenstein!” But that would be mistaken, for there is no monster, nor his novelistic creator, a modern-day Mary Shelley, behind this robot. Instead, there is Chuck Fletcher, who is one of an Internet community of people developing inMoov robots, part-by-plastic part, with 3D printers.

What’s that? you say. You’re right – InMoov is a lot to swallow in one gulp. But from what we can gather from the Maker Faire website, a deftly functioning robot (or ranks of them around the Internet) is emerging from the plastic sands, or resins, of 3D printers, which are amazing enough in themselves.

This is where you need to start: The Make site advises that Chuck Fletcher will be bringing to World Maker Faire “a fully articulated and animated 3D printed humanoid animatronic robot.” Got that? “The build,” Chuck continues, “is based on the open source inMoov project by Gael Langevin. This is an amazing project with hundreds of parts and a growing community of makers adding features like eye tracking, hand and finger control using the Kinect and LeapMotion devices.” Suddenly, there are too many “makers” to count and too much ingenious technology to readily grasp.

(One of the great potentials of plastic parts produced by 3D printing, Langevin notes virtually as an aside, is for prosthestics, or human body parts.)

Be sure you take a few minutes to watch Gael Lsngevin’s emerging winsome, yet intent, robot lift a red ball of something from “his” right hand to his left, raise it to his eyes for “inspection,” then drop it on the table before him, followed by what you might call, possibly, a celebratory gesture. It’s easy to feel that you’re on the verge of a bigtime something (again, not Frankenstein) under construction across the Internet – from printed-out plastic parts. Wow! (There’s more on the plastic angle on the MakerBot Thingiverse site.) – Doug Bedell

Comments

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.”

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

Comments

‘Twitter Thinking’ in Tech Writing

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

My 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:

Perform system troubleshooting
Completing required surveillances
Equipment repairs and replacements
Creating backup copies by copying plant equipment files

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:

System troubleshooting
Surveillance
Repairs and replacements
File backup

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

Comments

Quizlet’s for Learning

Posted on July 16, 2013
Filed Under Education, Technology | Leave a Comment

You may already know about Quizlet, or maybe your kids do and haven’t told you of it yet. Chances are their teachers know about this web learning service – and likely love it.

We’ve just happened upon Quizlet and it appears to be a great means of creating your own “flash cards” or tests in any field you chose, or taking advantage of many that have already been created by users of the site. Name a subject, and it appears likely there will be a Quizlet test, or tests, for it. And there’s a lady’s voice that reads off titles and other information to help you get acquainted with any territory you’re interested in.

Entranced by Quizlet we’ve turned, where else, to Wikipedia to learn more about it. It turns out that Quizlet is “an online learning tool created by high school sophomore Andrew Sutherland in Albany, California, in 2005 and released to the public in January, 2007. “As of April 2011,” Wikipedia adds, “Quizlet has over 8.7 million user-generated flashcard sets and more than 2.8 million registered users.”

Wow! Andrew Sutherland’s fortune is made! Except that Quizlet is free. But there is (we bet you’ve already guessed) an evidently more expansive Quizlet Plus for $15-a-year. Hence an income stream. “As a memorization tool,” we’re told, “Quizlet lets registered users create ‘sets’ of terms customized for their own needs. These sets of terms can then be studied under several study modes.” And, naturally, there are Quizlet Facebook and Twitter feeds.

By gosh, you could probably enter an entire nuclear power plant’s components into Quizlet and study them from your laptop, wherever you are, if you’re so-minded.

We are getting used to this, but we never fail to be amazed at the useful learning aids we find surfing the web. Quizlet, and Andrew Sutherland, are clearly part of learning’s future.

Yet if anyone had told us there was an Albany, California, we’d have told them they were mistaken. We’re from New York – but we’ve got more learning to do. – Doug Bedell

Comments

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.

“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

Comments

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?”

Erwin 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

Pinterest for Tech Writers? You Bet!

Comments

Persistence Rewarded M.J. Hurley

Comments

A Versatile Writer, Based on a Boat

Comments

Subheads for Clarity, If not Beauty

Comments

An Engaging Robot’s Emerging from the Internet’s Plastic ‘Sands’

Comments

Apostrophes Matter When You’re Claiming to be Careful

Comments

‘Twitter Thinking’ in Tech Writing

Comments

Quizlet’s for Learning

Comments

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

Comments

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

Comments

Recently

Categories

Archives

Blogroll

Find It