Alan Brandon

Last month I wrote an article for Gizmag.com about the Santa Barbara Instrument Group’s AllSky horizon-to-horizon camera. The AllSky’s main gig is extended, unattended sky watching. Point it up, switch it on, and you’re good to go.

The AllSky is meant for tracking clouds, meteors, UFOs, and whatnot. It features a high-gain CCD sensor in a weatherproof housing, complete with a heater to prevent the build up of condensation.

With props and apologies to Sonia Simone over at Copyblogger, from whom I totally stole the idea and foundation for this article, here is my list of the top seven harsh realities of technical communications.

Sonia’s article, The 7 Harsh Realities of Social Media Marketing, looks at the “not-so-kumbaya” aspects of marketing using social media. As I was reading, it struck me again how similar marketing communications and technical communications can be. And I realized that the harsh realities in Sonia’s article have corresponding realities in tech comms. Unlike Sonia, I can’t think of a single kumbaya aspect of tech comms though.

Harsh Reality #1: No one is reading your blog
The tech comms correlation: Nobody wants to read your manual

Your customers (don’t call them users all the time, you’ll forget where your salary comes from) DO NOT want to read your manual, help, PDF, wiki, support website, or wiki. They just want to use the product they bought from your company, preferably with no learning curve or “unexpected operation”.

And your customers really don’t want to read your “About this manual” section. Sure you have a solid, logical scheme for bolding command names, italicizing menu choices, bolding and italicizing soft-key functions, but… Nobody cares.

Harsh Reality #2: You’ve got to give (some of) your best stuff away
The tech comms correlation: You’ve got to give all of your technical communications away

Make your manual, help, and so on available for free. Don’t hide it behind a pay wall or registered-user section of your web site. You don’t need to protect it; your competitors already know everything about your product. If you hide your user documentation, you are just making hard on your users customers.

Harsh Reality #3: It will eat your life (if you let it)
The tech comms correlation: Learn to let go of perfection

In social media marketing you worry that if you log off, you will miss a comment, blog post, or tweet. In technical communications, many writers worry that they have missed a style tag, an Oxford comma, a split infinitive. Let it go. Do your best with the schedule you have and your documentation will be good enough. If it’s not, your customers will tell you.

Harsh Reality #4: Social media hates selling
The tech comms correlation: Don’t market in your manuals

By the time your customers crack open your configuration guide they have already been sold on your product. That’s how they became customers, right? Your documentation should show them the best way to swing the hammer, not go on and on about how cool pounding nails is.

Harsh Reality #5: What they say is a million times more important than what you say
The tech comms correlation: The same!

What your customers say about your documentation and about your product is just as important as what you have to say about it. If you customers say it’s hard to find anything in your quick reference guide, fix it. If your customers say it’s too hard to power on the unit, rewrite the Getting Started section.

Harsh Reality #6: A blog is not a marketing plan
The tech comms correlation: A manual is not a functional spec (and vice-versa)

It is tempting — oh, so tempting — to “repurpose” the design document or functional spec to create the user documentation. Don’t do it! Your customers deserve more. A functional spec may have a lot of great information in it, but its audience is different. It’s purpose is different. Your customers need information that is designed to meet their needs, not the needs of the development team.

Harsh Reality #7: You don’t get to opt out
The tech comms correlation: Somebody’s got to write this stuff

Social media and collaborative technologies may have their place in technical communications, but your organization still needs a technical communicator to plan, develop, and maintain your user docs. You plan you products; why would your documentation require less? Even wiki-based documentation requires a moderator and manager. Useful documentation needs the strategy and experience that technical writer provides.

“Making the case for web content strategies – Common questions from the content creator” is the title of a great diagram created by Richard Ingram. (Click for a larger view.)

As Richard says:

Hiring an external contractor to help create useful, usable, and enjoyable web content without a comprehensive content strategy raises too many questions and stops them dead in their tracks.

Via @halvorson on Twitter.

Sure all the cool kids are doing it but is collaborative, social, conversational product documentation really the best way to meet your customers’ needs? Despite the buzz, Web 2.0-based documentation can act as a roadblock to getting your content to your readers.

Ellis Pratt at Cherryleaf has a good summary of some of the problems experienced by organizations that had made the move to wiki-based documentation:

Users were struggling to find information they wanted.

The wiki-based user community platform was incomplete, out-of-date and incorrect in places.

The content was the most viewed content of all the literature her company produced, but no-one wanted to take responsibility to manage the content.

The Documentation team did not “own” the community content, but whenever there was an issue, they were asked to fix it.

Users saw it as official information, but the organisation saw it as unofficial information.

[Management] didn’t want to spend the team’s precious time editing user content at the expense of writing new official content.

They had a continual battle with content spam.

It was hard to migrate content between the formal and informal documentation sets.

Some of these issues can be addressed organizationally, and others must be addresed by infrastructure. Many of the features of traditional publishing that we have come to take for granted (namely, predictable, repeatable navigation) have been crippled or lost in the movement to adopt “good enough” publishing tools and strategies.

I just viewed a great presentation by Melissa Rach called “10 things every business person should know about content strategy”. Whether you’re in the content creation biz or not, this is an excellent introduction to how you should be thinking about your content (if you’re not already).

Here are the “10 things” highlighted in the presentation:

1. Treat content like a critical business asset.
2. Content needs dedicated oversight.
3. It’s never too early to think about content.
4. Understand your content’s environment.
5. Document your content ecosystem.
6. Don’t underestimate the content creation effort.
7. Ask why. Start small.
8. Assemble the content team before the work begins.
9. Content needs care and feeding.
10. Be prepared for change.

There’s a lot of good stuff in Rach’s presentation. She works at Brain Traffic, where president Kristina Halvorson has written the book called Content Strategy for the Web. I plan to check out the book soon and will report my impressions here in the future.

(via justwriteclick)