It's always an interesting time for those of us in user
assistance when we're given a blank slate and told to document something new.
You feel like it's a loophole in time. You get to start new and perhaps do
things a little differently. It's a time to ask ourselves, how can we make our
help better or how can we improve the style of what we write.
Many of us on our team have been doing that recently as we
prepare to bring you new software over the coming years. It's a process we
continually go through in the software world - improve and add more features. And
whenever we improve or add more features, we create new documentation. It's a
never-ending fun cycle (for the nerds, like me, who love writing user
documentation).
I've been working on some new functionality recently. And in
particular, I've been working on creating some visual representations of
concepts in the new software using Microsoft Visio. It's interesting to say the
least as I try to visually connect ideas that are interrelated in the program.
However, drawing a few boxes on a page is not exactly helpful. Quite
the opposite, I'm delighting in using skills I learned about in school with my
experience documenting software the past four years. I like thinking about how
you can take information you want people to learn and think about how best to
teach. Some people need to see visually how different areas in the program
connect. Some people need screenshots to compare what they see on the screen to
our documentation of how it works. Some people just want the written
instructions so they can follow 1, 2, 3. There are so many options for user assistance
but choosing what works best is the critical part of truly helping users learn
what they need to so they can perform the functions of their job and be
efficient.
So back to these visios I've been creating. I get kinda
goofy excited when I get to work on them because I get to jump back and forth
from overview writing to supplementing that text with a visual concept. That's
probably my favorite thing about software documentation - the interrelation
between text and images. Or as we called it in school - information design. Everyone
has his or her niche, but this is mine. I've always been a geek about learning
and now I get to help others learn for a living.
Time will only tell if my work will help users. I'm
realistic, it may not help all users, but if it helps some, then I'm a happy
camper. When we officially publish the documentation, I'll be sure to do a new
post and show you what I eventually came up with.
In the meantime, do you use visual concepts or diagrams in
your documentation? Or, if you're a
user, do you like seeing them and does it help you?
I received an email yesterday about the changes coming to
Microsoft Office 2010 and specifically a big kudos to their introduction of
some new help techniques. Along the way, I have always felt Microsoft products
introduced new ways of helping users. From that annoying paper clip guy (who we
don't like to admit really did help us from time to time) to the right pane
which allowed us to view a multitude of help information, to tooltips, and to
the myriad of ways Microsoft embeds help in the program and doesn't just point
you to the help file. Naturally, these have been cool ideas we've tried to
emulate but we always wish we had their resources to pull off some of the more
technical ideas. I'm not saying we aren't awesome, just that a company the size
of Microsoft has infinitely more people, time, and money. However, envy aside,
it's always important to have at least one company in your field introducing
new ideas. And in the last five years, many new players to the user assistance
field have given us plenty of ideas to pursue.
However, Microsoft's latest change in embedded help has me
wondering how it will or will not change the game of helping users get the most
out of the software. Game= key word. You see, in Office 2010 as I learned from
ZDNet's Christopher Dawson,
Microsoft is using their ribbon in the program as a training tool. With the
ribbon, they are turning it into a game (Ribbon Hero) where you try to compete
for achievements in the program. You can even connect your Ribbon Hero to
facebook to brag to all your friends about how well you are doing. You earn achievements
by learning how to use the program and all its features - an often critical
point of Microsoft software (and software in general) is you don't use enough
of the features to warrant the cost or upgrade.
The Office 2010 team leaned on the Xbox group to learn the
motivational strategies and factors in console gaming. If people are so
addicted to WoW, D&D, FF, PS3, Wii, Xbox, and Facebook games (mafia wars
or farmville anyone?) would those same gaming strategies translate to
productivity software?
It's an interesting idea and I'm on the fence. I like the
concept of making learning more fun. Hence, the Fun Theory (an initiative from
Volkswagen). See this great video on YouTube as an example.
However, while making learning more fun is good, I don't see
people wanting to turn productivity software into a video game like experience.
When I want to have fun I pop in Little Big Planet on my PS3, I don't open Microsoft
Word to learn more features. After all, how you can you get the escape from
life experience when you're opening up a program to do... work
<<ugh>> 
.
CareerCast.com conducted a study on the top 20 and worst 20 jobs of 2010. Technical writer landed the no. 13 spot for top jobs of 2010. Other tech related jobs include Software engineer, Computer systems analyst, and Web developer.
For the full list of top 20 and worst 20 jobs of 2010 check out Reuters.
Are you new to documentation and need somewhere to learn about where to start? Check out http://www.indoition.com/. They have checklists, links to various software and websites, and assist you on how to select your authoring, screen capturing, and screencasting tools. Overrall, this is a good place to get started (or freshen up) on your venture as a Technical Writer.
Do you remember when you first got your job and signed paperwork regarding policies and procedures? Some of you may have even had to sit through the sexual harassment video or re-enactment of sexual harassment situations. But did you ever have to watch a video about what your companies policies are?
Well, Telstra, an Australian Telecom company, created a video about their policies regarding the use of social media sites, for the world and their 40,000+ employees to view. You can view the video here.
I am all for moving forward and using new technologies to deliver information, on sites like YouTube and eHow, you can find tutorials on just about anything. Even here at Blackbaud, there are video tutorials available for our software, but there are just some things that I feel is better fitted on paper. What do you think?
source: http://mashable.com/2009/12/16/telstra-social-media/
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.
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.
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.
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.
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.
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?
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 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?
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:
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?
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.
More Posts
Next page »