Alan Brandon

I love style guides almost as much as I love disagreeing with them. That’s why I’m excited to get my hands on Yahoo’s new house style book, The Yahoo! Style Guide. The style guide is available in hard copy (starting July 6) but much of the content is available on Yahoo’s style site at styleguide.yahoo.com.

I’m glad to see Yahoo has axed a lot of hyphens: 3D, not 3-D; email, not e-mail; and website, not web-site (in which they agree with AP).

Oddly, Yahoo offers Ni-MH for nickel-metal hydride (as in the batteries). Typically chemical compounds are not expressed using hyphens (NiCad anybody?).

Lifehacker puts it nicely:

As with any style guide, nothing’s written in stone—just because Yahoo or AP declares a style doesn’t mean it’s the only correct way (sorry Yahoo, but we’re sticking with “internet” rather than “Internet“)….

Based on my brief time there, the yahoo style site looks like a good resource. I’m looking forward to getting the book as well.

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.

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)

Wikipedia will soon add video to their online encyclopedia. That’s pretty cool, but what’s even more impressive is that they will eventually be adding web tools to allow Wikipedia users to edit the video online.

From an article on Technology Review:

The project also includes developing Web tools to create smooth methods for transferring and editing videos. When a Wikipedia editor finds relevant snippets, he will be able to preview them, and set the “in” and “out” points, without having to worry about file conversions.

The convergence of words, pictures, sound, and video is getting closer to “seamless”. With in-browser tools becoming more widespread (photo editing tools in Flickr, for example) the breadth of media available for techincal communicators is greater than ever before. I know this will benefit information users and consumers in the end (as soon as tech “writers” figure out how to take advantage of the new tools).

via 2moro docs.