Documentation Survey Results and Responses

The 2009 Q1 results for the documentation survey have been compiled. Here is a quick summary of our key findings for Q1:

• We received 153 responses in Q1 2009. That, my friends, is a new record. And with all those responses comes a ton of great feedback (more on that in a minute).
• For our five overall rating categories - Accuracy, Completeness, Easy to Understand, Accessibility, and Usefulness - the most frequent rating was a 4 or 5 (out of 5).
• Our highest overall rating category was Accuracy. (Mean = 4.26)
• Our lowest overall rating category was Easy to Understand. (Mean = 3.82)
• 72.4% of survey respondents were able to find the answer to their question in the documentation the last time they accessed it.
• The last time our respondents had a question, we were able to help 62.5% resolve the issue on their own with documentation instead of them having to contact Customer Support.

I like compiling the statistical data and comparing trends from quarter to quarter. Those metrics are important and help us understand our weaknesses and strengths. But my favorite thing about reviewing survey results is reading all the user feedback. You can really get a feel for the struggles and pains users experience when they can't complete tasks. For example, when a user says he can’t run an import because the guide doesn't explain which fields are required, that's great information. We can work with that. It requires no trend analysis. And when we call the user, even those who sound upset or angry in the survey, they are typically appreciative that we responded, and usually have even more input for us. It's a great example of how this survey helps us improve our documentation.

Likewise, you can sense the relief when a user is able to find information he needs and perform his job better. Knowing that the documentation is helping users and doing what it's supposed to be doing is great to hear. It validates a lot of hard work and effort.

Here are some of the responses collected this quarter (names withheld to protect privacy):

"PLEASE expand the documentation for Dashboards! There is not enough information about functionality with Share Dashboards and other descriptions are not detailed enough. I've had to do a lot of trial and error and testing on my own."

"Create a guide to explain Actions and Action Track creation."

"I would recommend that when the user guides are updated that an email be sent out to inform us."

“I really appreciate having the user guides. I go there first. Yes, I am pleased, too, with the Knowledgebase, and the telephone support. However, I will almost always first go to the user guides, because I want to know as much as possible about the topic with which I'm dealing, and the user guides point out features I may either not understand, or features that our organization is not yet using. So, typically do I not only find an answer to my question, but I learn something else I can apply.”

That’s just a sample of the responses we got last quarter. I look forward to reading the survey responses every quarter because I know I’ll learn different things about our users and how they use our documentation. So if you've ever wanted to know if users really do read our documentation, the answer is a resounding yes. We hear from them every day.

To be entered in our 2009 second quarter drawing, complete our online survey. It takes only a few minutes. To send us feedback about our user guides or help file documentation at any time, email documentationcomments@blackbaud.com.  

Twitter - Can it Make You a Better Technical Writer?

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:

1. Twitter forces you to be concise.
2. Twitter forces you to exercise your vocabulary.
3. 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?

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 -

1. Losing the reader
2. Making the reader feel stupid
3. Failing to stick
4. Being a total bore
5. 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 do you explain technical writing to a kid?

The short answer is… you don’t!

Last Friday, I had the distinct privilege to be part of a special field trip for kids from Meeting Street Academy (See Rachel’s blog post for more background on the special event). In short summary, I was to explain to four and five year olds what I do for a living. Hmmm… technical writing in the eyes of a child.

Here are some things I thought of…  (and yes, please feel free to laugh at my feeble attempt)

1. Do you like to read?
2. What books?
3. Do you like to make up stories?
4. Do you like playing on the computer?
5. Add that all up and you can be me!

See in my mind, I was trying to explain how a kid their age who loved reading and stories somehow became me as an adult with this career that involves playing with things and writing about it. I even showed them the *books* we write and how they have pictures (screen captures).

I really wanted to explain how curiosity was important in my education and career but wasn't exactly sure how. However, I think in general I was supposed to show them that it’s important to read, to learn how to write, and to stay in school. I loved how they liked to raise their hands to ask questions, that’s a good sign! Being eager to learn is definitely a part of technical writing.

I’ve given plenty of talks about technical writing before (to college age kids) but this experience gave me a chance to see what I do through the eyes of a child. And, I laughed. It’s not exactly possible but I think just seeing someone who has a job they love and enjoy is important. I hope they continue to see positive examples of people who applied their learning to a cool career. If one of them happens to take on technical communication, all the cooler.

How would you explain your profession to a child?

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

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? 

4th Quarter Documentation Survey Winner

Each quarter we enter the respondents of our online survey in a drawing for a $25 Amazon.com gift certificate. The 4th quarter winner for 2008 is John Kraus of Evangel University. Congratulations, John!

We received 93 responses in Q4 and 284 overall for 2008. Our survey ratings and statistics remained consistent throughout 2008 and we continue to receive valuable client feedback.  

And remember, to be entered in our 2009 first quarter drawing, complete our online survey. It takes only a few minutes. To send us feedback about our user guides or help file documentation at any time, email documentationcomments@blackbaud.com.

How can we produce effective yet efficient user assistance content?

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

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?

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?

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.

Journey from Structred Frame to SharePoint Server Wiki

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?

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...

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

Vintage Documentation

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

Documentation Survey 3rd Quarter Results

On October 9th, Justin announced our third quarter documentation survey winner. I thought it might be nice to discuss some of our results from the survey with our blog readers.

A link to our survey appears on the Blackbaud User Guides pages (accessed from the Support menu), this blog, EE/FE/SIS Help files (a test run), and in the support newsletters once each quarter. We received 73 responses in Q3 2008.

Overall Key Findings:

• For our five overall rating categories – Accuracy, Completeness, Easy to Understand, Accessibility, and Usefulness – the most frequent rating was a 4 or 5 (out of 5).
• Our best overall rating category was Accuracy. Out of 73 responses, 62 rated us 4 or 5.  
• 72.6% of survey respondents were able to find the answer to their question in the documentation the last time they accessed it.

Question: Please give an overall rating for the following aspects of documentation (user guides and help files only) on a scale of 1 (least favorable) to 5 (most favorable)?

Discussion:
While we are pleased our numbers are mostly 4’s and 5’s we are actively looking for opportunities to improve and we even received some great suggestions from the open ended responses on the survey.

Question: Which Blackbaud product were you using when you accessed the documentation (user guides and help files)?

Discussion: While we are always pleased with the number of responses for The Raiser’s Edge, we are looking for ways to improve the amount of feedback we receive for our other products. While we know we don’t have as many users on The Patron Edge as The Raiser's Edge, we value each user’s feedback equally.

Question: The last time you had a question, did you find the answer in the documentation (user guides and help files)?

Discussion: We are happy to have so many “yes” answers to this question. We hope it means you find your answer quickly and get back to completing your tasks. However, we also see that 27.4% of you did not find your answer. This question is one of our critical ones. We’d love for to you always find your answer. Our numbers have been improving in this category but there is always more room for improvement.

Here are some sample user comments and suggestions pulled from the survey (only initials to protect the privacy of our clients):

User guides are enormous. Small, more streamlined versions, maybe for more discrete tasks would be helpful. I frequently find myself selectively printing only the relevant sections of a guide.
TH

The user guides are easy to understand and are helpful. I like being able to find an answer without having to call customer support.
JH

Love the support offered by Blackbaud, especially easy access to the User Guides - don't have to buy a hard copy, and don't have to deal with free documentation that is purposely incomplete in effort to get me to buy the manual! Good job Blackbaud. Always happy to recommend your company.
AB

Your User Guides are very extensive and frequently help me answer my questions. However,
sometimes when searching I get results that are not dealing with the program I specified.
JF

I especially like the guides when I want an initial overview of the module. They are well organized and explain the technical aspects very clearly.
MT

Discussion: I think the open ended comments are my favorite part of the survey. It's not easy to quantify the information but hearing exactly what you think is critical. And, we take what you say to heart. If you allow us too, we try to follow up with as many people as possible especially when they offer up suggestions, areas for improvements, or mention problems. For example, to the user who mentioned the guides are enormous we would try to see if it would have been better for the user to search for the answer in the help file versus the user guides. Sometimes it can be a matter of choosing the right resource in the situation. And, we do realize that we are unable to help every user every time because there can be situations when contacting the help desk is the right decision.

Thanks again to our Q3 survey respondents! And remember, if you take our survey, every quarter we enter the respondents into a drawing for a $25 Amazon.com gift card.

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

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!)