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.

Like a Good Gardener, Help an Enterprise Keep Itself Current

Posted on October 18, 2016
Filed Under Uncategorized | Leave a Comment

Here’s a great analogy for technical writers from the “Stories From the Software Salt Mines” blog. Sure, you can keep adding features (in the form of text and photos) to whatever technical content you’ve been developing for months, or years.

But if you haven’t been conscious of keeping it all fresh and organized appropriately, if you’ve just been adding on…and on, watch out. Or if you’ve been describing an aging system as though it’s still new, that could be a double whammy.

“Software as a garden: to be able to grow more software, to be able to grow revenue with it,” the blog writer notes, “you have to keep the soil fertile and give the roots room. The problem is, gardening projects are a hard sell. These are things like refactoring older parts of the code that no longer serve efficiently, or upgrading or replacing outdated parts of the architecture, or redesigning subsystems that work fine today but can’t adapt to things the company wants to do in the future. When you tell executives you need to do these things, what they hear is that they can’t have new features while you do it. New features fuel growing companies.”

In short, you need to be observant, that is, current, as you write. If the setting you’ve been active in has been aging (and what settings haven’t?), have you kept it current in your own awareness and thoughts, and pointed out to its owners what you’ve been observing?

If you’re simply chronicling an aging, though originally awesome, system, watch out! If you don’t “tend your garden,” contribute to keeping it current, sooner or later it will stop producing. And nobody should be surprised at that.

Yet, notes the writer in the Software Salt Mines: “It was much the same story: the company had focused entirely on rapid new-feature delivery and not enough on ongoing design and architecture. After a decade, their soil had gone infertile and the code had become tangled. Nothing new would grow.”

A good gardener helps maintain the conditions for growth. So does a good technical writer. – Doug Bedell

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

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

Putting It All Together

Posted on June 16, 2016
Filed Under Uncategorized | Leave a Comment

Interana Inc. is a behavior analytics company in Redwood City, CA., an organization in which Neal Kaplan is the Senior User Assistance Manager. Kaplan has 20+ years experience as a technical writer and distilled his experience into a presentation at the recent Write the Docs conference in Portland, Oregon.

Kaplan was concerned with relationships between the documentation and customer support units of organizations, “Two Great Teams that Work Great Together,” or need to, to be sure. He’s posted his slides on the Web and they’re well worth experiencing, as though you were at the meeting.

The people who write manuals and other support materials have to be working in concert with their colleagues who provide direct support to an organization’s customers. That’s a truism that needs to be achieved in daily practice. “We don’t want customers to shut up and go away,” one of Kaplan’s slides reads. “Happy customers = more dollars” the next one notes.

What occurs when the two presumably collegial units aren’t in synch? “Frustration” proclaims Slide No. 31. There follow a number of steps Kaplan recommends to insure that the two groups are indeed working together toward a common aim.

“Knock down silos” is prime among them. Insure that the document writers and the document interpreters are working together for clarity and mutual understanding, relationships that can then be shared with customers, to everyone’s gain.

Kaplan delivered his message to 400 attendees at the Portland conference and is now sharing it with many thousands more on the Web. It’s a message that never wears thin: Technical writers have had to accomplish much in terms of training and experience to get where they are. But all that effort is of little use to anyone if it’s not shared with empathy and clarity with colleagues in other departments and their hoped-for customers in the wider world.

Super-evident? Probably. Readily practiced? Not always. Absorb Neal Kaplan’s slides. – Doug Bedell

Apt Guidance from a Pseudonym

Posted on December 15, 2015
Filed Under Uncategorized | Leave a Comment

Here’s a survey from an evidently active technical writer of today’s tech writing market. We say “evidently active” because he uses a pseudonym – “krypted” – to disguise his identity on BuzzFeed. That’s excusable, though, because it’s a candid, informative post.

The technical writing market, krypted advises, has changed dramatically over the past 15 years. “That was before everyone had a blog and a dozen different revenue streams,” he notes. People aren’t “just writing books and letting publishers market them” any longer. There are new routes to prominence as a self-supporting technical writer.

The new “routes to the writing market” include:

• Corporate technical writing – Writing manuals and blog posts for companies.

• Advertising on your website – Be careful here, but if you’ve got “a decent amount of content, and get a good amount of traffic” advertising running alongside it “can be a great revenue stream.”

• Self-publishing – You can self-publish books on sites like Amazon and Apple’s iBooks. “There are also print on demand publishers out there that will let you upload your book and then print the copies required when people purchase books.”

• Magazine articles – “You can make about half as much as many books pay, while only writing around five pages of content.”

• Writing articles for websites – This form of writing has replaced “most magazine publishing efforts. Many websites with niche markets can pay pretty well.”

• Writing books – “I decided to keep this in here. Because you can still find a publisher who wants to publish your book…”

• There are other avenues for income, like: Consulting, Training, Conferences (speaking “to get your writing brand out there”), and Kickstarter (crowd funding).

You’ll note that most of these avenues have digital foundations; sure enough, that’s increasingly the nature of today’s writing world.

Don’t expect, krypted advises, to make a bundle right off, if at all. But exposure, primarily digital exposure, counts a lot. “At first, it’s all about exposure. If you’re a seasoned author who’s been focused on one medium, hopefully this article gives you some ideas for other things to go after. The world is changing, getting more interconnected…”

And so, indeed, it is. “There’s value in all of our efforts. Picking the ones that you focus on is just a matter of choosing which you value most.” That’s krypted’s much appreciated closing thought. – Doug Bedell

Information (Most of It Anyway) Is For Sharing

Posted on October 8, 2015
Filed Under Uncategorized | Leave a Comment

This needn’t be long and won’t be. But there’s a post on a blog called “Customers and Content, Ideas and opinions about customer-focused documentation” that deserves both comment and assent. The blogger, Neal Kaplan, a San Francisco Bay area technologist, is bothered by employees who hoard information, thereby withholding it from colleagues. Unintentionally and unwittingly, maybe, but they do it, and it’s wrong.

“Information gets locked in the heads of professional services, customer support, QA, sales…” when it may have much wider organizational pertinence.When it’s not shared, what ought to be a common effort is hobbled, sometimes drastically so.

“Customer support will have a knowledge base in their support tool, professional services will have a wiki, marketing will use Slack, but there’s no central repository of corporate knowledge,” Kaplan writes. “Every team has their own knowledge base, but they might not be shared with other teams. They might not know that the other knowledge bases exist, which is why they created one in the first place.”

Teams? These aren’t teams, they’re groups of “athletes” who don’t share what ought to be common signals. Organizationally, do you think they’re scoring as effectively as they could be?

Somehow, what should be obvious, isn’t always so in organizations. Technical writers are apt to recognize information impasses sooner than others because they often poke around among departments looking for threads of a common problem.

Some material with personal or proprietary significance, of course, may not be appropriate for sharing, but that’s not what were’s talking about here. Information of enterprise-wide operational significance is what we’re concerned about.

So, share, guys share! Your organization, which represents, doesn’t it, your own future, requires it. And by the way, Neal Kaplan ought to give himself a byline on his own site. He’s got a photo posted, but you have to go to “About Me,” and then “How to contact me” and find that his email address is “nealbkaplan@gmail.com” or his Twitter handle, “nealkaplan”, to find him out. Not that he’s hiding his identity, presumably. – Doug Bedell

Notations on Note-Taking

Posted on March 14, 2014
Filed Under Uncategorized | Leave a Comment

The value of note-taking can be enhanced if your notes are taken mindfully, rather than merely routinely. That’s to say, annotating technical notes while they’re still fresh and prompting new insights can extend their reach and value.

We’re glad to see T. R. Girill pick up on the value of mindful note-taking in a post on edutopia. He reminds us that Henry David Thoreau’s artfully taken field notes on the flowering times 0f 500 plants near Concord, MA, in 1851-58 “are still used today for comparison with current climate-change data.”

Even so, as Girill adds, though most notes are made for use by the note-taker only, they can have enhanced value by being promptly perused and expanded on virtually on-the-spot. Don’t do anything, one might add, simply to risk letting it go stale.

Girill’s reference is to Erick Greene’s chaper (Ch. 12) in Michael R. Canfield’s book on Field Notes on Science and Nature (Cambridge: Harvard University Press, 2011). Greene is a biology professor at the University of Montana, who urges science students, Girill observes, “to widen the scope of their note-taking to extend beyond just observations or numerical data” to include such enhancements as memory and organizational aids, commentary, interpretation and conjecture.

There’s no time like when the pen is “hot” to dash off such additional insights. That’s know as being truly engaged in your work. Jot down your enhancements in the margin of your page, or wherever there’s white space to profit from. – Doug Bedell

An ‘Atwater Kent’ Geiger Counter

Posted on September 6, 2012
Filed Under Uncategorized | Leave a Comment

Now, here’s a technical novelty. John Baichtal, community manager at the Make blog and magazine, features a homemade geiger counter that looks like an “old-timey cathedral radio with a detachable wand,” rather than the usual metal box with a dial on it.

It’s a beautiful job, we think you’ll agree. Geiger counters like this would add some serenity to a few nuclear power plants we know. It was made by somebody with the web moniker “moustachenator.” But all we can find out about him (we presume, but maybe we shouldn’t) on YouTube is that he’s apparently 65 and lives in the U.S. The “count” numbers flash on nixie tubes.

The builder details the 12 steps that were involved in creating this antique-looking counter. Congratulations to “moustachenator” the maker, indeed! – Doug Bedell

A Writing Blogger Who Has It Right

Posted on July 13, 2012
Filed Under Communication, Technology, The Writing Life, Uncategorized | Leave a Comment

Friday the 13th has turned out to be my lucky day, in a tradesman’s sense, at least. I’ve just come upon John Graham-Cumming’s blog on technical writing and it’s great to have discovered a kindred spirit who reaffirms what little I thought I knew about writing. To the fullest.

Graham-Cumming is a British computer programmer and writer. His pointers are right on the mark: Practice, Read, Listen to Editors, Think about writing, Think about the reader, Plan and Dream. That’s it, and it’s plenty.

Writing is a discipline, but a hazy one. There are explicit things to do, yet inspiration comes first, and that’s where the dreaming comes in. Technical writers have it over their more creative colleagues in this respect, because their material is relatively “dictated,” it’s permissible parameters are clearer. Yet writing well always involves reflection and rededication, whatever the subject assignment. Hence the dreaming factor.
Read more

Ways To Get The Sleep We Need

Posted on August 15, 2011
Filed Under Uncategorized | Leave a Comment

Here’s something all of us have an opinion on: sleep. Sleep is a good, necessary thing, but how much of a good thing is enough?

Ivan Walsh on the klariti.com blog for small business people has some cogent things to say about sleep. Indeed, they’re worth staying up for.
Read more

keep looking »

Like a Good Gardener, Help an Enterprise Keep Itself Current

Cruising Clearly Through a Product or Process

No ‘Catch-Up’ Practiced Here

Putting It All Together

Apt Guidance from a Pseudonym

Information (Most of It Anyway) Is For Sharing

Notations on Note-Taking

An ‘Atwater Kent’ Geiger Counter

A Writing Blogger Who Has It Right

Ways To Get The Sleep We Need

Recently

Categories

Archives

Blogroll

Find It