From the Doc Side : Help

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?

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.

Have a Helpful Idea?

Lindsey Robbins — Thu, 20 Nov 2008 18:56:00 GMT

Your suggestions are heard. Yes, I know it can be hard to believe sometimes but some people (finger pointing at me and the rest of Blackbaud) love to listen. Listening is fun because you don’t have to pretend to know everything. You can let others share their unique experiences, thoughts, and visions with you. And then as Shaun Sullivan said, steal it as your own genius idea. Okay, I don’t think I really have the guts to claim credit from anyone (and I'm pretty sure he was joking) but I do dig hearing other people’s ideas and researching them further.

In fact, a bunch of our technical writers were sitting in Shaun’s Emerging Technology session at Blackbaud’s Conference for Nonprofits this past Monday and listening. He was discussing how you can search the Infinity apps and how it intelligently provides results including an index of our help. And a great question was asked… Can you pull in a 3rd party help to be indexed as well?

Hmmm… good idea!

As our senior technical writer said in the session, we’ll look into it. And let me say, I’m pretty sure we’ll have some great discussions and research about it. Either way, I want to acknowledge that the question was great!

So what’s the point?

I just wanted the opportunity to say we’d love for you to share any other ideas you have. None are bad. All ideas, even in the most basic form, can be sparks for improvement, conversations, and even other ideas. To submit a good idea, leave a comment on the post (login or register for free in the upper right corner) or email us anytime at documentationcomments@blackbaud.com.

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?

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?

Video Tutorials Debut in the Blackbaud NetCommunity Help File

Nikki Tremann — Wed, 06 Aug 2008 13:44:00 GMT

Does this sound familiar? A coworker sends an email asking you to explain how to do something. You begin your reply, feverishly typing out the necessary steps and details. Half a page later it dawns on you -- it would be easier for both of you if you simply walked over and showed them what you're trying to describe.

Welcome to Tech Writer World! We often face this dilemma when trying to describe a complex process using static text and images. Since we don't have the ability to drop by our users' desks to explain in person, we're happy to announce that we now have the next best thing -- video tutorials! Video tutorials are short demonstrations you watch in a browser that show and explain how to do something in the program.

Our first video tutorial, Processing Individual Signup Requests in The Raiser's Edge, debuts in the Blackbaud NetCommunity 5.5 help files. Let us know what you think and we'd love suggestions for other processes in Blackbaud programs you would like us to address in future tutorials.

Blackbaud's Next Generation of Help - Part 3

Denise Kadilak — Tue, 01 Jul 2008 12:15:00 GMT

Now that we have looked at what Blackbaud enterprise help offers our end-users and their clients - Part 1 and Part 2 - this week we will take a look at the technology driving the help system. We will also talk about how this technology serves to make our search functionality cutting edge.

Technology

As I mentioned in Part 1, the server-based help system is designed to be installed on a Web server along with the Blackbaud Enterprise application itself, which is deployed as a ClickOnce rich-client application. In the help system, HTML topics are wrapped in Microsoft ASP.NET version 2.0 code, which interacts with two Web services that call the code from the application. This technology enables us to display context-sensitive information and dynamically generate links to topics for all the functions a user has rights to on a given page of the application.

Implementation

All “pluggable” features in the application support linking with help topics: tasks, search lists, reports, data forms, pages. Pages in the application support multiple help topics: root page level, page level actions, page sections, and page section actions. Each of these items is associated with a “HelpKey” property in the code. By default, HelpKeys are specific HTML filenames of topics within the system. But end-users can modify HelpKeys (no coding necessary) and include other file types that display in a browser (doc, pdf). They can also link to fully qualified URLs. See Part 2 of my series for more information about manipulating help keys in the system.

As a result, when a user accesses our help system from any given page, a GetPageMetaData Web service builds a list of links related to functions on the page to which a user has security access. The help content for the page (usually an overview) appears, along with a scrollable pane on the left side of the screen containing the dynamically generated links, allowing users easy access to all help associated with the selected help topic.

Search

Blackbaud’s help system depends on Microsoft Indexing Service, which extracts content from files and constructs an indexed catalog to facilitate the user’s search. The service is initialized and configured for Blackbaud Enterprise help on the Web server with an install utility that is part of the application.

The Search field is available from every topic in the help system (via the ASP.NET wrapper). When a user executes a search, an ASP.NET handler issues a query against the indexing service search catalog, which is configured to include all files in the application Help directory. Each time the service indexes the catalog, changes to existing files, as well as new files are included. So end users can add their own documents or topics to the Help directory, and these files are included in search results.

The results are returned and displayed in a dynamically generated html page.

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.

Blackbaud's Next Generation of Help - Part 1

Denise Kadilak — Fri, 13 Jun 2008 12:59:00 GMT

Early in 2005, Blackbaud Inc. started work on an enterprise version of our constituent management software product. We targeted the software to high-end users interested in a powerful and customizable product, and of course, we wanted the help system to be equally powerful and customizable. From this desire was born the Blackbaud Enterprise help system. Currently employed in four different applications, the enterprise help system provides on-demand, context-sensitive help, dynamically generated links, and is fully customizable. In the coming weeks, I plan to specifically address each feature. In this my first help post, I provide an overview of how the system works on the client side.

Access Help

The server-based based help system installs on the client's Web server along with the application and can be accessed in a number of ways. From any page or screen in the application, to access context-sensitive help information, a user can:

Click the Help button
Press F1

In addition, from the help page, the Contents button opens a table of contents and the Index button accesses a detailed help index. A Search field is also available on every help page, but we will talk more about this functionality in a later post.

Procedures
When users access a procedure page in help, the page appears displaying a brief explanation of the functionality and an expandable procedure link, keeping the page neat and tight - no scrolling.

Users click the link to expand the procedure.

Reference Information
Screens in the application usually include a number of fields and options. Because we do not want to bog down our procedures with a laundry list of field explanations, we arrange this information in a separate table, easily accessed from a link included in the procedure. These reference topics are also presented as context-sensitive topics when help is called from a given screen in the program.

Conceptual Information
The concept pages in the help system include information explaining the concept governing a function.

Dynamically Generated Links

In addition to displaying the called help information, the help system dynamically generates links to other areas in the help related to tasks, actions, sections, and other items included on the page from which the help is called. For example, a constituent page is composed of a series of tabs and includes a list of tasks you can execute from the page. If a user calls up help from a constituent page, the help page displays a detailed explanation of the page, and the links displayed on the left side of the page take the user to additional help information specific to each tab and task.

Next Week's Blog

As I mentioned in the introduction, users can customize the help file to better meet their specific needs. Next week, we will take a detailed look at this customization feature.