From the Doc Side : conversations

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?

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.

Be a Part of the Conversation

Lindsey Robbins — Mon, 09 Jun 2008 21:48:00 GMT

How often do you think about the conversations you have with your constituents or users? Are you thinking about the synchronous real time conversations - the phone calls, the meetings, the special events? If you are, you're overlooking one of the most important conversations you're having with your members, users, or constituents. The conversations we have that aren't in real time can make or break your success. Some examples of asynchronous conversations are reports, journal articles, policies and procedures, legal notices, emails, websites, twitter, SMS, promotional materials, and more. No matter the medium, every user is seeking an answer.

This concept was perhaps the most interesting from a thought process perspective from the conference I attended. The session I attended was from Ginny Redish on Writing as an Asynchronous Conversation. It made me think about how I write and how every piece of documentation we write is an ongoing conversation with users.

So, whenever you write something, ask yourself, what question am I answering? You can see if you're answering questions by looking for the verb. Conversations usually start and progress with one. For example, check out Amazon.com's login page. What question are they asking you?

In the software world, we've been answering questions for a long time. A dialog box is a form of question. Do you want to delete this very important file forever and be doomed two days from now? Click Yes or No! We, of course, click No and curse ourselves out later. However, the key element is the program asked me a question. The conversation was started by the software and I gave a dumb answer, but an answer just the same.

Over the years, in software documentation we've added more conversations via context sensitive help (F1), help files, user guides, tutorials, and more. No matter how we do it, we have to evaluate whether we are answering your questions. If we aren't, what can we do better? See, another question!

I suggest you ask yourself the same thing. How are you doing in your conversations?

For example, try answering these questions -
"How is my money being used?"
"How can I help your mission by volunteering?"
"When is your next special event?"
"What is the latest news from your organization?"
"The economy isn't great. I don't have a lot of money, but I want to help. What can I do?"

How did you do answering the questions? And, more importantly, where are you answering them? We can't always rely on real time conversations to answer questions, we have to be effective with every means of communication or software available.

Sometimes, your users or constituents won't know the correct question to ask. In those situations, try to think out the questions for them and answer them in advance. Provide them with the conversation starter and they're more likely to be engaged.

And remember, people don't have an infinite amount of time. They really will only participate in the conversation long enough to get their answer. Therefore, all your communication whether it's real time or not needs to be concise, clear, and efficient. Don't provide lots of and lots of text that users will balk at when they see (for example, this crazy long post is not a good conversation starter ). Keep your answers to the point, ask yourself if you're answering a question, and validate by having others review your work.

After all, it's not really computer to human interaction. There is a person on the other end of the computer and they need human to human interaction. All these great tools like Twitter, Facebook, Google, Raiser's Edge, Blackbaud NetCommunity, Education Edge, and more are tools. They are the medium that connects you to your people. Are you using the tool to create conversations?

Here's a short reminder…
1. Keep conversations short and on topic.
2. When you write something, identify the question being answered.

And remember, over these short asynchronous conversations you're having with constituents, users, and members, you are developing relationships. It's not always about making the pitch where you win or lose people, it's how you handle the short, quick conversations on a daily basis.