From the Doc Side

Q3 Documentation Survey Results

Justin Ward — Tue, 03 Nov 2009 20:25:00 GMT

The Q3 documentation survey results have been compiled. Here are some of the key stats:

We received 183 responses.
For our five overall rating categories - Accuracy, Completeness, Easy to Understand, Accessibility, and Usefulness - the two most frequent ratings were a 4 and 5 (out of 5).
Our highest overall rating category was ‘Accuracy’ (mean 4.30).
Our lowest overall rating category was ‘Easy to Understand’ (mean 3.98).
86.3% of survey respondents access documentation often or sometimes.
47.5% of survey respondents prefer to access documentation as user guide PDFs online.

Additionally, we have begun tracking user guide downloads with Google Analytics. This quarter we had 25,145 downloads from our User Guide pages. That number includes our user guides, video tutorials, and print tutorials. The number does not include hits on our hosted BBNC help files, which we track separately by topic.

And last but not least, each quarter we enter the respondents of our survey in a drawing for a $25 Amazon.com gift certificate. The Q3 winner for 2009 was Heather Flynn of Olive Crest Homes and Services for Abused Children. Congratulations, Heather!

To take the survey (and be entered in our 2009 fourth quarter drawing), click here. 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.

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.

User Guide Downloads and Survey Numbers

Justin Ward — Wed, 15 Jul 2009 15:06:00 GMT

In April of this year we started tracking the number of user guide downloads from our website. Using Google Analytics, we then filter the information by date range and/or product, depending on our reporting needs. I should point out that in addition to user guides, a ‘download’ could be a tutorial, quick reference sheet or video. Any type of help content we create and post on the User Guide pages can be included in the download count.

So how many downloads you ask? From April 28 to June 30 we had 22,862 downloads from our User Guide pages. That sounds reasonable to me. In fact, it sounds like a lot of traffic pulling down information from our User Guides pages, but we really don’t have any recent, reliable data to compare it to. I think we’ll just have to keep our eye on those numbers over the next few months before we begin to evaluate and gauge overall usage.

Survey Numbers
We received 182 responses to our Documentation survey last quarter, once again setting a new record in total responses. Last year at this time we were averaging between 50 and 75 responses each quarter. We thought the number would go up a little when we added the survey link to our AES help files, but we’ve seen a substantial increase. This is the third consecutive quarter that we’ve received over 100 responses. And even though it requires more time reviewing those responses, it’s a great trend, and one we would like to continue.

Before I forget, the 2nd quarter winner for 2009 is Kim Abel of the Desert Botanical Garden. Congratulations Kim.

To be entered in our 2009 third 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.

Meet the Team - Steve S.

Lindsey Robbins — Thu, 09 Jul 2009 18:05:00 GMT

Name? Steve S.

How long have you been at Blackbaud? Going on 4 years

What technology from the past do you wish would make a comeback? The flux capacitor... I could always use a little more time in the day!

Favorite part of technical communication? Working with multiple products, learning about new technology, and the adrenaline rush and creative high that accompanies routine deadline doom.

Products you Work On? The Raiser's Edge, Blackbaud Enterprise CRM, and Blackbaud Payment Service

Other projects you Work On? PCI Compliance, usability, consistency, and localization. I also cartoon for the company employee newsletter, The Buzz.

How did you get into technical writing? My career as an indie comic book creator, while fun, didn't really pay the bills... Luckily, I was able to apply my talents as a technical illustrator and then technical writer.

What's changed about Blackbaud since you've been here? The CEO and the ever-growing headcount.

What hasn't changed? The onsite fitness center remains the best perk I never use.

What's one unique thing about you? When not working to meet deadlines at Blackbaud, I work to meet deadlines as the staff cartoonist for the local alternative weekly newspaper.

Anything else? Nope.

Documentation Survey Results and Responses

Justin Ward — Wed, 29 Apr 2009 14:44:00 GMT

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?

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?

How do you explain technical writing to a kid?

Lindsey Robbins — Tue, 24 Feb 2009 16:51:00 GMT

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)

Do you like to read?
What books?
Do you like to make up stories?
Do you like playing on the computer?
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?

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?

4th Quarter Documentation Survey Winner

Justin Ward — Thu, 19 Feb 2009 15:51:00 GMT

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?

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.

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.

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.