From the Doc Side : suggestion

Forget Best-Selling Audio Books, Listen to Our User Guides for Free!

Lindsey Robbins — Tue, 20 Oct 2009 14:08:00 GMT

Did you know you could listen to our user guides read out loud for free? Well, if you have the free Adobe Acrobat Reader or even the full Adobe Acrobat installed on your Windows computer you have the ability to not only read our guides but listen to them as well. It's a little known feature that may be of use to you.

In Adobe Acrobat Reader, on the menu go to View, Read Out Loud. You can select to listen to the entire document or just the page you are on. Adobe uses the basic Windows voice settings so if you aren't able to hear anything, go to your Control Panel, Sound and Audio Devices, Audio tab. On the Audio tab, ensure you have a device selected for the sound playback.

If you want to adjust the voice or playback speed for the read out loud capability, go to Control Panel, Speech, Text to Speech tab. I personally went with Microsoft Sam on my computer, I like his deep monochromatic voice. If only they made a CP-30 voice.

Have you committed a technical writing sin?

Steve Pham — Fri, 27 Mar 2009 19:40:00 GMT

I’ve been re-reading some old posts in the field, and after reading Amy Hoy's Slash7 post on "How Tech Writing Sucks: The Five Sins," I started thinking… is it really possible not to commit any one of the five sins?

The Five Sins -

Losing the reader
Making the reader feel stupid
Failing to stick
Being a total bore
Not providing much-needed context

Hoy says the five sins are results of "bad" writing, but can you realistically prevent these things from happening for all users? As a n00bie in the field, I’m learning how to ensure the reader is getting what she needs out of the documentation. One objective of documentation is… user needs help, refer user to a guide or help file, user resolves issue on her own, and in doing so, saves user time and a phone call to customer support. Pretty simple... the objective at least seems that way, but now comes the tricky part.

How do you keep the reader engaged with relevant, lively content, without feeling stupid, so she can remember it the next time she completes the process?

Seems straight forward, but then again, we are discussing user guides and help files. These materials aren’t usually opened unless there is an issue, and then they are closed as soon as the issue is resolved. I guess what I am proposing is, these sins are sometimes inevitable. Here’s why…

You will lose the reader as soon as the issue is resolved.
No matter how you write, you’re going to make some reader feel stupid – either talking above or below them.
Most of the time, the content users are looking for is not everyday occurrences. Failing to stick is predictable and they will have to search for the answer again.
No matter how pretty you make it look, technical documentation is not going to be the most exciting type of reading available. How many manuals have ended up on the bestseller’s list?
Can you document everything? Probably not. So anytime a user cannot find something she is looking for, she is going to find it lacking.

I understand we are supposed to write in a way that best prevents this from happening, but perhaps it’s just the nature of the beast. You can’t expect to satisfy everyone can you? But I bet you can expect to commit one of these "sins.” What do you think? Can we strive for and achieve sin-free technical content? And if not, is it good enough to learn from our mistakes and keep improving as we go along?

How can we produce effective yet efficient user assistance content?

Lindsey Robbins — Mon, 02 Feb 2009 18:25:00 GMT

One of my esteemed co-workers shared this awesome article with me last week and now I want to share it with other writers of user assistance content in the field. If you haven’t read it yet, Mike Hughes’ article Straight Talk: Surviving Tough Times as a User Assistance Writer is a great read and quite thought-provoking. When I can squeeze in some time, I really want to thoroughly read it and make some notes about his main article points. There is a lot to digest in his post.

It came at a great time for me as I’m learning our team’s updated writing style. I’m learning how we’re tackling one of the article’s main points, how do you keep improving your user assistance content to meet audience needs while also being efficient with your resources and time?

Hope you enjoy the article!

Lick the button

Lindsey Robbins — Fri, 09 May 2008 20:58:00 GMT

On our team, I’m still one of the newbies. Even though I’ve been in the technical communication field for 4+ years now, 2+ at Blackbaud, I’m surrounded by seasoned veterans who have geek speak coursing through their veins. It can be intimidating. I should feel like I’m past the rookie phase at least but it’s hard when I’m around other technical writers who can knock out a tough new feature in record breaking speed. Okay, maybe it’s not that dramatic but it can feel that way when I write, and rewrite, and rewrite some more because the language doesn’t sound right. Then, there are the times that no matter your best attempts at writing you make a silly little mistake that can produce really funny results. The most famous, not done by me though, is when someone wrote “click the button” but somehow missed the first c. I bet if we asked you to lick the button in a procedure you’d think twice about how effective that’d be to complete an import .

Last year, I did such a blunder in a piece of documentation I emailed to my team to review. Little did I know when I was copying and pasting that I didn’t get all of the “if” in “If you..” so inadvertently I would have completely offended all of you. Of course when my manager caught the error it made me gasp in horror. I was thankful we have processes in place for editing. Because even while I am a rookie, these types of mistakes can happen to anyone. We’re told repeatedly in school (at all levels) how important editing is and having a big blooper like that happen to me was a great lesson. You’re never too experienced to make a mistake and spell check won’t find everything. Make sure you take the time to have another pair of human eyes check your documents; it could potentially save you from some severe embarrassment.

Friendly Suggestion - Create an editing process in your organization so you know what you need to do with a document before you send it to your donors, important stakeholders, or the media. As my mother used to say… “Proper planning prevents poor performance.”

Do you have any funny examples of this happening to you?