From the Doc Side : user guides

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?

Vintage Documentation

Lindsey Robbins — Fri, 31 Oct 2008 14:52:00 GMT

Wired magazine published a great photo essay on classic instruction manuals. It’s funny and pretty cool to see how far we’ve come as a field. Although my team is in agreement, that poor guy from Apple - what was he thinking selling his share of Apple stock for $800?!

Check out the photo essay here:
http://www.wired.com/culture/design/multimedia/2008/10/ff_manuals

By Popular Demand - The Raiser's Edge 7 for Beginners

Steve Stegelin — Thu, 23 Oct 2008 17:40:00 GMT

We often get great feedback about our documentation from our users. Sometimes, it's a friendly head's up of a typo that made its way out into the world (d'oh!). My favorites, though, are when I get to help fulfill a user’s request or search for information by introducing them to a guide they simply weren’t aware existed. Let’s face it, there’s a lot in The Raiser’s Edge, and as such, there are plenty of guides to browse through (and glance over along the way).

So it was often frustrating to get that one request I couldn’t answer so easily: The request for the “one guide” that introduces the user to everything The Raiser’s Edge has to offer. A simple overview, painted in broad strokes, something for a novice user. Of course this was an obvious need—like I said, there’s a lot in The Raiser’s Edge—and the lack of a good answer was always the most frustrating.

So it’s with much pleasure to finally have an answer to that request with The Raiser’s Edge 7 for Beginners. It’s full of great, useful information, ideal for both the new users struggling with the daunting task of having to grasp everything The Raiser’s Edge offers and the experienced users looking to refresh their memories or explore other areas of the program. It’s also unlike any other user guide we provide for The Raiser’s Edge. Here’s an excerpt:

After you use the program for awhile, you will probably discover other navigation features and methods. Use the ones that work best for you. No way of navigating is necessarily right and no way is necessarily wrong; it’s a you say “potayto,” I say “potahto” kind of thing. Well, actually I usually just say “French fries,” but you get the idea.

Written in this humorous, lighthearted, and simplistic style (not to suggest anyone’s a Dummy), it covers the wide range of features available in The Raiser’s Edge, from records to queries, from reports to mail, and everything in between. You can find it here. (And now I can’t wait for the time a user requests the “one guide” that introduces everything The Raiser’s Edge has to offer!)

How do you like your help?

Lindsey Robbins — Mon, 11 Aug 2008 21:00:00 GMT

In the evolution of software help, user assistance content has taken many shapes and forms. The search for the best way to assist you in your every day work processes is an ever changing quest. Long, jargon filled, and confusing technical documentation is hopefully outdated. And hopefully too, the short picture diagrams with confusing instructions. How did we ever figure out how to put furniture together before technical communicators? However, we know that’s not always the case.

Why is it so difficult to make help easy? Well one difficulty is keeping up with how fast software can change but more so it’s about meeting user’s expectations for help in the program. Here are some questions we might struggle with on a daily/monthly/yearly basis –

User Guides -

When you access help, do you want a user guide?
Do you want to see the user guide on the screen side-by-side with the program or do you want to print it out and go page by page?
Do you take notes when you print the manuals?
Do you want a lot of detail or does that take up too much time and paper?
Are you a visual learner? Do we need more or less screen captures?
If we have more, that’s more pages and bigger file sizes.
Do you have the internet bandwidth to download big user guides?
How do we document everything but not overwhelm you with the number of user guides?
Do you learn by area of the program or depending on the process you’re performing?

Help Files -
Or, are you the type of user who doesn’t have the time for printed manuals and you just want your answer now. You want to search through a help file or knowledgebase and get back to doing your work.

If you are this type, how do you search?
Do you want similar information as the user guide or do you want just problem solving information?
Do you need visuals?
Do you need a glossary or index?
How do you want the help to appear in relation to the program?
How do you access the help? Do you want to hit F1 on the keyboard? Need a question mark icon to click? Or do you miss the days of Microsoft Word when that paper clip would pop up trying to guess when you needed help?

General Documentation Questions -
Then there is the multitude of other questions we might ask ourselves:

Do you want other user’s advice on what works or doesn’t work? Kinda like user reviews on store websites.
Do you want to be able to edit the content yourself?
Add a comment?
Do you want to save the documentation so you don’t have to remember it?
Do we need more web 2.0 types of content and how would we manage it?
And even more so, how can we marry the help files, user guides with other efforts in the company like knowledgebase, training, and support?

These are a few questions jumping off the top of my head. If I quizzed other team members, I’m sure this post would become exponentially longer. We do know from our documentation survey you still prefer having user guides. But we then have to manage how your expectations might change now and in the future. If we don’t start preparing now we won’t be ready then.

This topic really struck a note with me recently because a well respected technical communicator in the field decided to publish content for her users in the form of a wiki and stop creating manuals.

I’m interested in seeing how this goes. I’m aware that her audience needs might be radically different than ours but when you’re focused on day-to-day tasks it can be hard to remember to look out and see how our field is trending. I’m not sure what our users will ask of us in the years to come. It’s exciting and I know whatever you expect of us, we’ll do our best to deliver top quality.

Have any opinions?

Extra!! Extra!! Read All About It!!

Betsy Unger — Mon, 04 Aug 2008 19:38:00 GMT

BBNC 5.5 USER GUIDES POSTED!!

Greetings! With the BBNC 5.5 release, the documentation team is proud to announce that a new set of BBNC user guides has been released! New user guides include the Website Design Guide, Team Fundraising Guide, and the User Networking Guide. In addition, we posted a FAQ for your fundraiser team captains. The FAQ includes details about how to use the participant dashboard. We recommend you save the pdf and email it to your team captains.

To manage the list of guides, we updated the BBNC user guide page on our website. Now, after you click Blackbaud NetCommunity on the User Guides page, a BBNC “flavor” page appears. What BBNC flavor do you need? That depends on the Blackbaud product you integrate with BBNC. The four options are BBNC for RE, BBNC for BBEC, OCC for EE, and OCC for SIS (if that is not enough acronyms for you, I can go on…).

After you click the BBNC “flavor”, the entire set of user guides appear for that version of BBNC.

The list of user guides is listed below. For a guide that appears on each page, such as the Website Design Guide, the user guide is specific to the version you need. To clarify, the Website Design Guide that appears on the BBEC for RE page does not contain help content for OCC parts. OCC information is specific to the user guide pages EE or SIS.

Blackbaud NetCommunity Configuration Overview
Blackbaud NetCommunity Installation Guide
Program Basics Guide
Website Design Guide
Email Guide
Administration Guide
Chapter Management Guide
Team Fundraising Guide
Team Fundraiser Dashboard FAQ
Personal Page Management Guide
User Networking Guide
Blackbaud NetCommunity & The Raiser’s Edge Integration Guide
Blackbaud NetCommunity & Blackbaud Enterprise Integration Guide
NetConnection Installation Guide
Online Campus Community Update and New Features Guide
Online Campus Community &The Education Edge Integration Guide
Online Campus Community & Blackbaud Student Information System Integration Guide

Enjoy!! We hope you love what you see. These user guides are now broken out by topics and better organized. For you, our hope is this provides a way for you find the BBNC help content you need faster and successfully.

So, who needs a BB acronym test….?