From the Doc Side : user assistance content

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.

Twitter - Can it Make You a Better Technical Writer?

Steve Pham — Thu, 16 Apr 2009 18:19:00 GMT

Copyblogger's Jennifer Blanchard thinks so and I completely agree. According to the post "How Twitter Makes You A Better Writer", Twitter helps writers in three ways:

Twitter forces you to be concise.
Twitter forces you to exercise your vocabulary.
Twitter forces you to improve your editing skills.

Being fairly new to Twitter, I find myself constantly editing my tweets (the Twitter word for posts) to fit the 140 character limit. Because of this limit, you do have to be careful about what and how you choose to write your messages.

How does Twitter force you to be concise?
There is no getting around being brief. You write more than 140 characters, your message doesn't get sent. You learn fast, capture the gist of what you want to say, and quickly send it out.

Why do you need to exercise your vocabulary?
If you only have 140 characters and have to be concise, you want to choose the most effective words to get your message across without using ones you don't. So you start thinking about ways to say what you want with creative word choice and not extra sentences. Each word matters. When each word matters you think about them a lot more.

What's editing have to do with anything?
Because of being concise and evaluating each word choice, you often have to re-read your messages quite frequently to evaluate whether it's what you meant to say. But, you don't have all day to edit a tweet. Twitter forces you to write better in shorter amounts of time because a medium like this is all about being timely. The posts need to be fast yet good. You can't compromise quality just because it's a microblog. And, you want to send out good content that relfects well on the rest of your content and your skills. Editing well and quickly is of essence.

So how does this help technical writers?
Well a good portion of help authoring is to deliver information as effectively and efficiently as possible so users can get back to the task they were trying to accomplish. Technical information isn't prose or poetry. No one wants to read a book on how to turn on the computer. A tool like Twitter can make you aware of how important each word choice is but it can also teach you to get your message across sooner. As well, I find it encourages creativity in being effective. Creativity is always an important tool in staying relevant in technical communication as well as learn how to meet your users' needs with less space and words. People want help with their problem now and then to move on. Twitter is great then for teaching technical writers to focus on one problem or message and quickly move onto the next task. What do you think? Do you agree? Or, do you think tools and mediums like Twitter are ruining the English language?

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?

The life of a n00b...do you smell fire?

Steve Pham — Mon, 23 Feb 2009 16:10:00 GMT

Being the new guy on the team and having limited exposure to “true” technical writing definitely makes me feel a bit intimidated especially when there are individuals with 5-10+ years of experience under their belts. Immediately, I felt as if I needed to catch up and learn about the technologies, methodologies, and any other of the “-ies” words. This fire under my uhh…seat, wasn’t due to any pressure from the team, in fact, they encouraged me to learn at my own pace and not to feel rushed to get into anything. Phew…that’s reassuring.

Well, fast forward to two weeks later, and here I am writing this post, reiterating what I had learned about being a technical writer and user assistance.

First being a technical writer:

I mean technical writer…sounds exciting doesn’t it? I am sure plenty of us grow up saying, “Daddy I want to be a technical writer when I grow up!” However, in all seriousness, it is really an interesting and diverse position. This post about Unexpected Characteristics of Technical Writing summed it up pretty well. And here is my summary of that summary:

Requires a good amount of social interaction
Skills in:

writing
graphics
troubleshooting
coding
project management
usability
etc…etc…etc…

Knowledge of the software (hopefully this is obvious)

The last bullet was my biggest reason for becoming a technical writer. I love to learn, so what better way to learn and truly understand a product/software than to write how it works? I just learned the basics of a new software tool that we use and now I am excited to use it.

Secondly, user assistance:

After reading the article, What if Readers, Can’t Read?, I was certainly intrigued on how user assistance is shifting. Mainly, because I fit his statistics (as most people my age probably do).

For instance, an average college student buys a text book worth $100, but never opened it. Wow! I thought I was the only idiot who did that…that makes me feel better.

Here are some more shocking stats:

China will soon become the number one English speaking country in the world.
One in eight couples married in the US last year met on the Internet.
The percentage of university graduates from India with English language skills is 100%.

So what does this all mean? We have to adapt to the change of times. I know we are currently doing so by updating our Online Help Files on our new Infinity Platform. We are also constantly researching and understanding the new technologies that will make our jobs more efficient and make our users happier.

As I still have a lot to learn about a lot, I hope you will follow me on my journey to understanding the challenging and changing fields of technical writing and user assistance. And, help keep that fire under my seat going. Who knows maybe you’ll notice a few sparks under yours?

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!

Developing Trust in Help Content

Lindsey Robbins — Tue, 13 Jan 2009 19:48:00 GMT

One topic I am reading about, that I missed the discussion on over holiday break, is all this talk about whether people trust blogs on corporate websites. While I really don’t know where to put my two cents in about trust and corporate blogs (because I mostly write this blog just to interact with our users more), it did get me thinking about how you develop your ethos overall. In particular, I thought about how people learn to trust or not to trust documentation. Does it all depend on your first interaction when you search for help? Do you give up if you don’t find something on the first try? How do you decide whether you should trust the help content you are reading?

I know many times, depending on the product, my help file is an internet search on Google.com (scandalous coming from a technical writer, right?!). For some products, I trust the users more than the bare minimum, hard to find documentation.

However, I have read some product documentation and you can tell when the writers put in effort to be correct. I suppose that’s why I also like to blog, you get to be more transparent and ask for feedback. It’s why we do our survey too. We know you aren’t always going to find your answer on the first try, but because we care about your trust in us, we want to listen and improve. So if you ever want to tell us how we can earn/improve your trust in us, we’d be glad to spend some time hearing what you have to say. Then, it’s not asking for trust, it’s earning it bit by bit in our behavior on an everyday basis.

User-Generated Help: Future of Documentation?

Lindsey Robbins — Wed, 26 Nov 2008 18:07:00 GMT

Of late, I’ve been intrigued by something YouTube is doing. They are requesting user-submitted documentation in the form of videos. Well the video part makes sense, right? However, it’s interesting they are reaching out to the audience to supplement their official documentation. Is it fair to put the burden on the users? Fun for users to participate in developing help?

They are now doing a second round of submissions. You can read about it in their blog. And, you can review the round one selections.

One interesting thing, they didn’t ask for just any help submission, they provided a list of topics to choose from. If your video is selected, it is then posted side-by-side with their content. And, they claim their help gets 1 million + users a day. Not sure if I believe that or not but it’s still interesting (I've never clicked on the their help but maybe I'm an anomaly).

This is definitely a topic I’ll keep my eye on as help and documentation might be figuring out how to join the web 2.0 world. But then the question still remains, when do you ask for user-generated help? I mean, it might be a pure guess on my part but I don't see a million people rushing to create help content. Most people would rather visit the dentist then spend time explaining things to others. Unless you're like me. And if you are, welcome to my ~~crazy~~ cool world.

Journey from Structred Frame to SharePoint Server Wiki

Lindsey Robbins — Tue, 18 Nov 2008 11:36:00 GMT

The journey from last week to this week already feels a decade long as I’ve encountered many trials and errors in converting internal team documentation authored in Structured FrameMaker into a Microsoft SharePoint Server 2007 friendly format. In other words, complex framemaker to basic html.

I’m not complaining about the trials and errors. On the contrary, it’s been exciting to dig my hands into this fun little side project that keeps evolving and building.

Well really, I need to take you back three years to get to the root of where I’m at now. It all started with two separate projects. The first started as learning about how we generate help from Adobe FrameMaker using WebWorks and my lesson was our internal documentation help file the Tech Writer Master. Sounds intimidating doesn’t it? I spent a lot of time updating, organizing, and examining the information design of the help file. Unfortunately, a problem we frequently faced was there wasn’t an easy way to quickly and efficiently update the internal documentation. And as you know, processes, workflows, and general daily work information is fluid and changes often. So I kept the internal documentation as an interest especially because of my passion for knowledge management.

Then that summer, I was tasked along with another co-worker to research how we might, and whether it was valuable, implement our help file as a wiki. We ended up going a different direction with our Infinity help but I was able to bring in my wiki experience and often ask myself what role wikis could have in user assistance content. When the wiki project ran its course, I kept up with the free wiki tools out there and wanted to find a way to install on my own machine and run as a web server for my team. I knew ultimately that having the Documentation team work on a wiki would provide valuable experience in new ways of thinking about content management.

Months went by and my company rolled out Microsoft SharePoint Server 2007 as our internal company content management system. I knew SharePoint had some wiki capabilities but I had to test it and see if it could work for us. I ended up choosing a Wiki Site from their templates. I played with it and in a matter of days, I had a team wiki set up. It wasn’t perfect, didn’t have all the features I wanted (especially around navigation), and proved frustrating at times but I was able to get the basics of what I needed up and going. And once it was set up, I presented it to my manager who pushed me to present it to the team.

So now, a few months after my team presentation, my little baby project is growing and providing new challenges. Our team is in the process of implementing it and that means gathering content from everywhere it’s been spread out and organizing it on the wiki. Which brings me to the conversion of docs from FrameMaker to HTML.

I tried a couple different methods before deciding on a winner -

FrameMaker to PDF. From PDF, save file as html. Issue: Formatting errors especially concerning images. Would involve too much cleanup.
FrameMaker, save as XML. XML to HTML using an XSL stylesheet. Issue: Worked sorta, but it would take a long time to convert and would need to spend some time creating a style sheet that fit our wiki needs.
Winner: I ended up using a basic WebWorks dynamic html template to generate one html file per FrameMaker chapter. I quickly chose the mapping for the Source to WebWorks style but after a few times choosing the styles, I quickly figured out what I wanted for the output. In some cases, I was able to eliminate some formatting later on by choosing not to output certain Frame items. I still had to do some cleanup but mainly that was around cross-references and updating the file paths to the images.

While there is still some manual cleanup in generating the html files, I am glad to have a pretty easy process to get our current documentation into the wiki. And, I even have a new member of my team helping with the setup of the wiki. Between him and I, we’re going to get our team’s content up, properly formatted, and perhaps even some consistency in the style of the content.

My hope, start 2009 with our knowledge management system in place and ready to be updated in real time. To say I’m excited is an understatement. It’s pretty cool to turn an idea into a reality.

What Do Users Need?

Lindsey Robbins — Thu, 06 Nov 2008 19:09:00 GMT

A simple question. What do users need? My mind starts thinking about it and I realize there are just too many answers to mentally fathom. Recently, someone on my team shared a great link to discussion results from a recent CIDM conference.

http://www.infomanagementcenter.com/enewsletter/200811/third.htm

I thought the "What we learned" section contained a lot of great answers. Seems thorough but of course it can never be a complete list. Users' needs are ever evolving and ever changing.

However, one particular statement I've thought about before came up in the discussion.

Users need answers to their questions.

Obvious - Yes. Easy to execute - No. How can you ever provide all the answers to each individual's questions? The answer is you probably can't but you try to answer as many as you can and provide ways to answer the rest by other means.

In Documentation, we recognize that while we aim to help every single user, there are times where your particular situation calls for Knowledgebase or Customer Support. However, that doesn't stop us from trying. Your questions always provide us opportunities to improve our Help.

Here are the main lessons learned from the article...

Answer the users' questions and help them do their job.
Make it easy for users to find the answer.
Provide users access or links to related information.
Give users an easy forum for reporting issues and collaborating.
Give users information in a format that suits their work environment.
Technology is changing user expectations.

What do you think, does this sound accurate?

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?

Doing More with Adobe Acrobat and PDFs

Lindsey Robbins — Tue, 22 Jul 2008 15:55:00 GMT

I love research. I love it so much I research what we could be doing five years from now. I like to know things. Being prepared for upcoming changes is an understatement for me. When I went to the STC conference in June, I saw a demo of Acrobat 9. Wow, it did some slick things. However, it meant it was time to go back to the ~~drawing~~ research board. We've heard of some issues with the Technical Communication Suite that Adobe is promoting with Acrobat 9, so we aren't sure when we plan to upgrade. However, when you're researching five years out you don't worry about small details (I mean, who worries about broken software, lost files, and loss of productivity migraines?). However, this line of thought did produce some questions about what we can do with Acrobat now and what we might want to consider doing this next year, two years down the road, and five+ years down the road.

On the Documentation team, we use Adobe Acrobat as part of the process to create our user guides. Among the things we already provide in our user guides include - bookmarks, table of contents, index, cross reference links, space to make notes in the margins, and more.

A new feature we're testing on the Education Edge, Student Information System, and Financial Edge 7.77 products is a new bookmark - Search the guide. We thought we'd try to make the process to search through a PDF for your content easier. When you click Search the guide, Adobe's search feature opens and you can enter your terms. The PDF search function is pretty good and I use it often when I try to locate existing content. Instead of relying on users to know where in Acrobat to go to for the search feature, we've added the bookmark so it's visibly present when they open the PDF the first time. Simple change but yet we're hoping it improves the usability of the user guide.

For longer term research, I've been hearing about other ways to increase the functionality of the PDF. Recently I received an email about enabling PDFs for comments. In short, this feature would enable users to make comments or notes in the documentation as they use it (very web 2.0 like). I like that it takes information (user guides) our users have already said they like (in our survey) and expand its usefulness. An article from Shlomo Perets discusses some ways to enable PDF comments. For us, it would require an update to our Adobe products and with our issues in the Tech Comm Suite it's not a good decision for us to implement. While we wait for Adobe to sort out its business, I am going to introduce this idea to our usability team. We don't even know if this is a feature users would like so it's time to do some user research.

Other items I've heard about and would like to do user research include -

Information Design. Not really a cool new feature per say but I like reading blogs and articles about how people use content. We redesigned our user guides for the products on the Infinity platform. Now as our software evolves and user expectations evolve, it's good to stay current on the latest research.
Keywords. Add keywords to each PDF and then provide a way for users to search the user guides on our website. We've been looking into this for a while but have been having problems working around how we would do that with the current security settings in place (you have to login to see the user guides). Security issue aside, we have to see how this would affect our current work processes and what the return on investment would be.

However, I know we can't stop there. There is a whole field of information on readers that needs to be explored (you know, in between writing new documentation for all the millions of software product releases we have each month). I love that a part of my job is to look for new ways to enhance our documentation. So if you have any suggestions, tips, or tricks for Adobe Acrobat, please pass them on. Oh and if you have any knowledge of other tips and tricks for other PDF readers out there, I'd be glad to hear about those too. As long as the reader is free for our users, I'm willing to do the research on ways to enhance our user guides. Research on cool new user assistance features is about as cool as The Dark Knight (already one of my all-time favorite movies). In other words, it's too cool for school.

Documentation is Haunting Me

Lindsey Robbins — Thu, 10 Jul 2008 20:56:00 GMT

Even on vacation I couldn't escape documentation. While most people think technical writers explain software or some similar product (and it's true, I do) so many other forms of technical communication exist. On my vacation I was bombarded with other people's technical writing. It's like one of those things you never notice and then when you're aware of it, it appears everywhere.

Here are a few examples from my recent trip and the time spent in the great outdoors of Northern Michigan.

Planes. Not only did I have neat little instructions with pictures but I also saw a flight attendant reading out of a huge manual. I thought they had to memorize their stuff. And, I know pilots have thick books of instructions as well. Not sure if I'm more or less comfortable with the idea that flying takes so much instruction to complete safely.
I bought a bunch of new gear for camping. I did read the instructions and follow them for my tent, footprint, self-inflating foam pad, head lamp and screen house. I did not read it for my sleeping bag or SIGG water bottle. I should have for the SIGG because I was supposed to wash it before using the first time. Ooops. I'm sure a few chemicals still inside won't harm me, right?
Food. Do you notice how many food packages come with instructions and warnings. I am always reading the labels and not even thinking about who designed and wrote them.
Countless other items I completely ignored as I tried to disconnect for a few days.

Interesting observation about the camping gear. Years past the product pictures and instructions that they crazily throw in last minute were more frustrating than helpful. This time, I actually could figure out what to do based on the instructions. Either I'm getting better at this documentation interpretation thing or my field is improving. You decide. :-)

Blackbaud's Next Generation of Help - Part 2

Denise Kadilak — Tue, 24 Jun 2008 12:52:00 GMT

In my last post about our next generation of help, I provided an end-user view of our new help system and mentioned in passing the customization functionality. In this post, we will take a more detailed look at the customization feature.

Customization

All help topics in the enterprise help system are fully customizable. As part of the user's work-flow, we recommend that users cut and paste all topics from the default Help directory to a Help/Custom directory so future updates do not overwrite topics they may have edited.

Via a single change to a web.config file, users can specify that all current HelpKeys point to files in the custom directory rather than the default Help directory. Users can then open an HTML topic, enter their changes, and save the edited topic. The next time a user accesses this topic, the program calls the edited version. Users can also add new topics. All edited and added topics are fully integrated in the search and recognized by the application.

Tools built into the application make changing the help keys used for a given page, screen, or feature easy. Using a design mode tool, accessed from the application's Tools menu, users can access the properties screen from which help keys are assigned.

When a user clicks the ellipses in the HelpKey field, a topic browser appears, listing all available help topics.

The user simply selects the new help key he wants used in the selected area in the program and clicks OK.

Additionally, users can provide a URL or the name of one of their own files as a HelpKey. For example, a user can place a pdf version of his organization’s in-house policy and procedures document in the Help directory, then specify the pdf as a HelpKey for a specific page instead of the default topic. The next time a user accesses help from that page, the pdf document displays in the main content pane.

Next Week's Blog

Next week we will examine the technology driving the new Blackbaud enterprise help system and take a closer look at the search functionality.

The Funny Side of Help

Lindsey Robbins — Fri, 20 Jun 2008 20:26:00 GMT

The more I explore help on the internet the more I see humor being used in documentation. Most of the time, I appreciate the unexpected approach to help. But, am I the exception? I’ve often heard how difficult it can be to use humor effectively. Humor for the most part is not a universal language across cultures. We’ve been taught in technical communication to write as one voice. I still think it's a valid point because inconsistency in language can drive me bonkers. However, is the movement towards folksonomies and relaxed language in explanations pushing us towards the point where we can be completely casual with our users?

I’m not entirely convinced. It seems to me it depends on the software you are explaining. A site like Twitter or Flickr can be edgy because of the type of content it manages. Software in the business world doesn’t necessarily seem like ripe ground for experimentation. I do think though that exploring what language you use is a valid discussion point. Do we need to be formal? Does being too formal make reading for understanding more difficult? I know when I read for understanding I like to feel like the writer is talking to me instead of in a monotone generic voice.

What language do you use in your communications? Have you used humor? Or, do you have an opinion on the language we use in our help files and user guides?

If you have some examples of some funny help documentation, be sure to share those too.