Friday, September 26, 2008

Hot off the presses

I'm the proud owner (but not quite possessor) of the new G1 smart phone from T-Mobile. I get to wait a month before I get to actually have it so, in anticipation of my new toy, I got a hold of the Getting Started guide for the G1.

I did this for two reasons: 1) to learn about what I had actually bought and, 2) to see how T-Mobile approached this new user manual.

Aside from the unfortunate and glaring typo on page 18 (Goggle Mail), it's a nice piece of writing. It informs readers on the basic anatomy of the phone, how to turn it on, and other requisite details, but it succeeds particularly well for 2 reasons. 

Layout The document is written primarily in landscape layout with 2 "pages" of content on each real page. This means that the writer didn't really expect people to print out the file - good assumption - and that, to maximize what a person will see on their computer screen, landscape was the way to go because computer screens are oriented in landscape themselves. Smart.

Just the Facts The sections of the document are very short and straight forward, instructing readers on how to accomplish simple tasks. There's little to no fluff. Good.

Add these characteristics together and you've got a very readable document. Maybe more importantly, you've got a document that's easy to skim - who's really going to read anything like this cover to cover anyway?

So, T-Mobile, you succeeded in knowing your audience and giving them a very friendly user manual. I am sorry though that today's modern spell-checkers can't catch it when you spell perhaps your most important business partner's name wrong. Call me - I do proofreading.

Monday, September 22, 2008

Don't build a closet for your skeletons.

Boo.

If the software you're selling is going to have a few skeletons - and most likely it will - then don't give them a closet to hide in.

It's difficult to design software that is 100% self informative and logical in its use, especially if that software is complex or has more "under the covers" than on top. And your customers know this - they most likely don't expect perfection.

So, if your product has some areas that might not make the most sense, or are downright confusing, say so. Don't pretend in your documentation that these areas are normal or logical if they aren't.  

Now, I'm not suggesting you write a chapter called Where Our Product Sucks and Will Drive You Crazy, but you should include a section for Possible Problems where you can provide tips for navigating the tricky areas. Your customers will show their appreciation for this by a) not calling your help desk, b) training their colleague users, and c) not being annoyed with you.

Those are nice outcomes for such a simple thing, don't you think?

(Oh, and for your next release, maybe you can improve on those tricky areas and use the same Possible Problems section to brag about the improvements you've made.)

Thursday, September 18, 2008

What matters most?

I'm not an English major, so I know from experience that perfect grammar doesn't equate to perfect documentation. So what matters most?

Here're my top 5 writing priorities when it comes to helping your customers help themselves:

Know what you're writing: Do your customers need a reference document with organized lists and tables of data? Do they need a step-by-step cookbook for how to progress through a process? Or maybe they just need some well thought-out diagrams?  If someone's expecting one type, and you give them another, you're wasting their time and they aren't likely to forgive you or give you another chance.

Know who you're writing for: Yes, I know I shouldn't end a phrase with a preposition, but I'm ok with it. I trust you'll be ok with it. See that? I know who I'm writing for. Seriously though, if you're writing for techies, then give them what they need. If you're writing for parents who need to know how to assemble a toy, give them what they need. Your audience should guide your writing almost as much as your product should.

Call it what it is: If it's a box, say so. If it's a button, say so. If it's a tab, well, you get the idea. So many products these days, especially in the software world, create their own interface elements and try to create new language for them. So, do your customers a favor and call the things what they are. Don't make them solve any puzzles.

Don't create dead ends: Never allow your customers to get trapped in your product documentation. Make sure your writing always has a way out or a way sideways.

Let your product be heard: I've helped a number of companies write their product documentation and most of them feel inclined to write about every detail, option, variable and setting. But if the product itself informs the user about a certain feature, why waste time and space writing about it? 

The best self-service option is the one that isn't needed. If you do this well enough, you won't even need product documentation. 

Can you imagine that?