Wikis Need Some Love (and best practices)

Since June of 2006 I’ve been moderating wikis as a part-time job for a company in Seattle. And then soon after at Blackbaud, we’ve explored and researched the use of a wiki as a help file. Since then, I’ve been focusing my efforts on creating an internal documentation wiki as a team development tool. Through my experiences, I’ve learned a few things about how to encourage best practices in wiki use.

1. Before you implement a wiki, spend time populating it with common topics and a basic set of information. Don’t just hand out a blank one to your team and expect them to figure out what to do with it. By establishing content already in the wiki, people are more comfortable following an example.
2. Before and during implementation, you need to spend time on the organization. Pages will be added, moved, and deleted. You need to keep the pages organized so that users don’t freak out when they see a mess of pages. People like boundaries, rules, organization – it provides a comfortable structure for them to contribute towards.
3. People need prompts and templates. Thinking about style and creating easy to use templates always encourages people to contribute more. But don’t expect them to use these things perfectly, clean up will need to be done. And prompts are always good to help guide people towards the behavior you want them to exhibit.
4. Be an active member yourself. People like strong leadership in a wiki especially where so few will become active participants.
5. Don’t underestimate providing multiple modes of navigation. Search, most recently updated pages tool, traditional table of contents hierarchy, and tag clouds are just some examples. I’ve also had a lot of success changing up links on the main page to continually bring new content and pages to users’ attention.
6. Peer to Peer messaging works. People can easily forget what they were doing two minutes ago so I don’t expect them to think of the wiki all the time. Instead, it’s extremely helpful to send P2P messages to users with a combination of prompts and links.
7. Users really like recognition, polls, and comments. If you can include these three things, you’ll be doing well. Recognition for contributions may be only a pat on the back but it means a lot to community members. Polls are great for opinions and everyone has one. And comments, well that’s a way for community members to connect, ask questions, and in general feel safe from the pressure of actually editing a page. Chances are if you can get them commenting, you’ll eventually get them editing.
8. WYSIWYG is a given. But going above that, see if you can provide a way to make adding pictures, video, widgets, and more easier. This will not only make the wiki more dynamic but people aren’t always lovers of long pages of static text.
9. If pages are getting longer and scrolling gives you hand cramps, do your wiki users a favor and break up the content into sub-pages. You can then use the main page as a starting point and create links. Wikis aren’t meant to be books or just content storage. It’s interactive, ever evolving, and (shockingly) fun!
10. Don’t underestimate the importance of a good moderator/editor. Life in wiki land can easily get out of control if you don’t have someone watching, loving, and caring for your wiki. Or, it can get all dusty and desert like if no one provides some attention to growth whether it’s encouraging participation, providing opportunities to contribute, or keeping pages clean and organized. It will also help if this moderator/editor is an expert in the wiki topics because then they can verify the content as they supervise it. As we all know, wikis can bring the best out of our collective knowledge or the worst and when it comes to work wikis, we all want the best.
    

Those are just my top ten tips for wiki use but I’ll continue to post on wikis if anything new develops, if you seem excited about wikis, or if I learn something geeky cool that I just have to share with y’all.

And please, if you have questions about my experiences or if you have a problem and want to troubleshoot, just send me an email or add a comment below. I definitely would love to share my passion for wikis with others. I don’t know why it is, but something about community created content gets me all tingly inside.
 

Selecting a 'Reader'

In an upcoming release of our version 7 products, we are going to remove Adobe’s Acrobat Reader from the installation. Right now, if you do not have a Reader installed on your workstation, our install detects this and asks if you would like us to install Acrobat Reader. A ‘Reader’ is a free tool that allows you to view and print Portable Document Format (PDF) files. If you’ve ever opened a PDF online, you have some form of Reader installed. For example, you need a Reader to view the user guides on our website.

We’ve found that providing this option really isn’t necessary since nearly everyone already has a Reader installed, and because we want our users to have the latest version of their reader – something we cannot update between releases.

Available Readers
While Adobe’s Acrobat Reader is the most prominent (and most feature-rich), there are a lot of other free Readers out there as well. I’ve read some good reviews on these applications, but I can’t really recommend any because I’ve only used Adobe’s Reader. However, if you are interested in other options, a quick Google search will yield plenty of results. Wikipedia even has a complete list of free Readers and categorizes them according to operating systems.

Just keep in mind, you might be able to find a tool that takes up less space on your hard drive, or something a little faster, but that’s probably because it doesn’t have all the bells and whistles that come packaged with Acrobat Reader. For example, Foxit Reader's download size is 2.55 MB, which is less than half the size of Acrobat's, and Foxit promises to launch instantly, without any delay. That probably sounds appealing to most users, just be sure you aren't leaving any needed, and free, functionality on the table.

If you are interested in Acrobat Reader, you can download the latest version (currently 8.1.2) from the Adobe’s website at no charge.

Where's the download button?

Google posted on their blog today that Google Sites is now open to everyone. Curious as I am, I checked out what this new Google Sites feature was. After all, I knew they had acquired Jotspot a while back and now we get to see how they reconfigured it.

It appears to be a combination website/wiki creator. You can control who can edit the pages, view content, etc without having to know html. I love WYSIWYG more than I probably should but even that love will probably not make me an earlier adopter of this option for professional reasons.

The one major flaw in all these websites that make creating websites and wikis customizable and personal is the inherent flaw that instead of you controlling access to the information by having it on your own network, they are all hosted online. And if by some chance there is an option to host it yourself on your own network, well that’s where the fees kick in.

Even though this is a particularly sensitive issue for someone like me who works for a public company, I think it’s an important issue for every organization – private or nonprofit – to consider. I love the value of having software hosted but only if it’s done within the scope of a contract and ensuring your data is protected like we do here.

However, as massive as Google is and as smart as they have been with their apps in the past, I still don’t trust keeping our information on a hosted website. Too vulnerable.

This is something I’ll continue to follow because I have this ongoing dream to have an internal documentation wiki for the Documentation team. We have a lot of information that needs to be managed in order to successfully share with each other and pass on to future technical writers. I’ve been downloading and testing as many free apps as I can find with no luck yet. You need to have more programming knowledge than I have to install. I really think if they can make hosted versions online easy for consumers, why can’t they make installable versions easy too?

In the meantime, I guess it’s back to figuring out the good and the bad about Microsoft’s SharePoint wiki features. Yikes!
 

Online Dis-Connectedness

Seems like the more we move in this digital age to online connectedness the more we become solitary in our efforts. We sit crouched behind a laptop staring at the screen for hours on end typing messages to people on twitter, facebook, IM, or email (depending on your medium of choice). It seems every year I do less face to face communication and more i-communication. It’s a bad crutch especially for someone like me who feels awkward, weird, and flustered when I do try to talk to a real person. I feel the geek warning lights going off when I realize I do have to talk to someone instead of figuring out the solution on my own. That’s what we’d all like to do, right? We’d like to solve all our problems on our own and feel self-sufficient.

However, the more experienced I become in technical communication the more I realize for me that collaboration and communication with others is the key to understanding. There are too many obstacles interfering with real understanding in the digital world. For example, I may be writing documentation for a new feature. Before I can write, I have to understand. To understand, I often rely on conversations with the person who designed the feature, the quality assurance analyst testing the feature, the developer who wrote the code, and other technical writers on my team. I go to other team members quite frequently just to have them read what I’ve written because they make a great test audience. If they can learn based on what I wrote, I may be on the right track.

However, every time I realize I don’t understand something and I need to talk to one of the people above I feel unsure. I ask myself if I really need help. I read and re-read my notes thinking clarity will jump out at me. And then, instead of asking the question in person in a conversation I send an email. That one email turns into a series of replies back and forth all day long and I'm not sure the answer is easily obtained or understood well.

So why do we retract from a seemingly simple solution? Why do we avoid each other? The more I think about this problem the more I realize if we collaborated more we’d break down these barriers that computers have put up around us. I feel lucky in that on my team we do a lot of cross collaboration but I don’t think it’s that way for everyone. It’s certainly more difficult across teams.

I’m just wondering, are other people feeling that the communication age is creating barriers to understanding? Do we need to email less and talk more? Do we even have the time to talk? And if we do collaborate in person, how do we capture that knowledge created?

Here’s a quick mental test. Think back over the past 30 days or even the last 7. When you didn’t understand something, what did you do? Did you try to figure out a solution on your own? Email someone? Call someone? Or, did you actually talk to someone in person?

Email is my default answer. I use it as a substitute to a conversation because it feels less intrusive. They can answer me on their terms. I wonder how ineffective I am and what I can do to change.

Do you feel disconnected even when you are connected?

 

Integrating Emerging Technologies on a Daily Basis with Existing Work Processes

Something that’s been on my mind a lot lately is the role of emerging technology and how to incorporate it into the documentation process. I’ve known about some of these emerging technologies for a long time but lately I’ve been thinking more about how we would actually go about implementing them on a daily basis. We all want to reach our users in the best possible medium with the most effective means. I especially feel that way about our team at Blackbaud. As a team, we’re always talking and trying to improve our processes and products (for example, see the post on our survey).

For example, I’ve been thinking about these emerging technologies…

• Blogs (how we’re going to best use our From the Doc Side blog)
• Wikis
• Client contact databases
• Latest usability trends (including how to best use results from our survey)
• Adobe’s Technical Communication Suite
• XML and Structured Authoring
• DITA
• Twitter, Facebook, and all other social networking ways to connect with other professionals and users
• User feedback in help files
• Short video demonstrations in PDFs (Adobe Captivate flash videos)
• 3D PDFs (see this example from Adobe)
• SEO (search engine optimization)
• iPhones and the trend towards mobile phone Internet use
• and the list goes on…

However, whenever my brain feels like it’s about to explode, this “but…” appears. It’s this reminder to myself that no matter how cool you become with emerging technologies you still have to do the basics well. I could write a piece of documentation and find this cool new way to make it easily accessible right when you need it most but if I don’t write the explanation very well in the first place, how helpful am I really being to you?

So no matter how much I like to learn and understand all the newest technologies and tools appearing out of nowhere on a constant basis, I want to make sure I’m still doing my basic tasks to the best of my ability.

And, along with doing the basics well, I have to remember that just because we have the power or the ability to do something amazing doesn’t make it the right decision. Just maybe, if people are asking you for a splash pool in the backyard they may not be quite ready for the ocean. Sometimes the simple solution really is the right one even if it’s not the most cutting edge.

Perhaps the answer to my solution to incorporating emerging technologies is to introduce these exciting developments in manageable small chunks and evaluate their effectiveness in an ongoing basis. I don’t want to overwhelm my users and myself when it’s possible for us to get there just not right now.

As you can see, I’m still learning this concept called patience because if I could, I would change into a superhero and improve your world in a day. I know you’re the same way too. So since we’re not getting fitted for red capes anytime soon, let’s work together on this process and see how we can do the basics well. I think if we spend time on the quality and really listen, we can incorporate emerging technologies on a realistic timeframe that’s comfortable for everyone.

What do you think? Have you put any thought to how you're going to integrate emerging technologies into your work processes?
 

Documentation’s Online Survey

Last year, the documentation team created an online survey to capture client feedback about our help content. We’ve done surveys in the past, and while we typically came away with valuable information, we always wished we’d gotten more responses. So this time around, we tried something a little different. Instead of the survey being a one-hit-wonder, we decided to leave the survey up indefinitely -- or as long as our users keep responding.

So far, this approach has worked well. The survey went live last year, and to date, we’ve received over 300 responses. Now, when we evaluate the data, we have more information to base our decisions on, and we can compare response trends from quarter to quarter.

What do we do with the information?
The whole purpose of this project is to improve our help content, both in the help files and user guides. We review survey responses on a weekly basis. When we need more clarification about something a user said, or when users have problems with our documentation, we contact them (just the users who give us permission). All this feedback is then compiled and shared with the team. When we analyze the data, we look for trends in responses so that we can focus our discussions.

For example, we recently focused our improvement efforts on five specific Raiser’s Edge user guides. By reviewing the survey data from the past year, we knew where the problem areas were in these guides. I don’t think we could have honed in on these guides and made meaningful changes without having such a high volume of client feedback over an extended period of time.

We've restructured and reorganized guides for other products as well, improved indexes, and added additional cross references to make our content easier to use. We found that in many cases, we had the information users needed, but they couldn't find it!

Right now, we are averaging 50 to 75 responses per quarter, and I hope this trend continues. If you haven’t taken our survey and would like to, click here. And don’t forget, each quarter we randomly select one of our survey respondents for a $25 Amazon gift card.

(Liberty Bell + Cheesesteaks + Rocky) x STC = Professional Development

The countdown is on… 19 days, 23 hours, and change until I’m going to professionally develop in Philly, PA. This professional development comes in the form of my first professional conference. Each year, two tech writers from our team attend the Society for Technical Communication’s annual conference. This year there are 130 sessions scheduled on all topics in technical communication. To say I’m geeked to attend is an understatement. However, the one minor detail I need to spend some time on before I leave is which sessions to attend. Choosing is going to be very difficult.

There are several things for me to consider -

1. What will enhance my team’s knowledge in the field of technical communication?
2. Is there anything I can learn to better help our users?
3. What can I learn to improve my own professional future?
4. Which presenters are the most knowledgeable in the field?
5. And, which presenters will waste my time?

You know that last one is true. Despite how awesome a session’s topic sounds, it really does depend on the expert giving it. The conference is June 1st – June 4th, 2008. And, I will be posting what I learn on here.

In the meantime, any advice on all things related to conferences?

I’m guessing I definitely need to have a coffee in my hand at all times, correct?

Lick the button

On our team, I’m still one of the newbies. Even though I’ve been in the technical communication field for 4+ years now, 2+ at Blackbaud, I’m surrounded by seasoned veterans who have geek speak coursing through their veins. It can be intimidating. I should feel like I’m past the rookie phase at least but it’s hard when I’m around other technical writers who can knock out a tough new feature in record breaking speed. Okay, maybe it’s not that dramatic but it can feel that way when I write, and rewrite, and rewrite some more because the language doesn’t sound right. Then, there are the times that no matter your best attempts at writing you make a silly little mistake that can produce really funny results. The most famous, not done by me though, is when someone wrote “click the button” but somehow missed the first c. I bet if we asked you to lick the button in a procedure you’d think twice about how effective that’d be to complete an import .

Last year, I did such a blunder in a piece of documentation I emailed to my team to review. Little did I know when I was copying and pasting that I didn’t get all of the “if” in “If you..” so inadvertently I would have completely offended all of you. Of course when my manager caught the error it made me gasp in horror. I was thankful we have processes in place for editing. Because even while I am a rookie, these types of mistakes can happen to anyone. We’re told repeatedly in school (at all levels) how important editing is and having a big blooper like that happen to me was a great lesson. You’re never too experienced to make a mistake and spell check won’t find everything. Make sure you take the time to have another pair of human eyes check your documents; it could potentially save you from some severe embarrassment.

Friendly Suggestion - Create an editing process in your organization so you know what you need to do with a document before you send it to your donors, important stakeholders, or the media. As my mother used to say… “Proper planning prevents poor performance.”

Do you have any funny examples of this happening to you?

Welcome!

Welcome to the Products Documentation Team Blog! We are very excited for the opportunity to connect with you in this new way. After all, everything we do is about you!

Our Documentation team is part of the Product Development department at Blackbaud and we create user assistance content. For example, have you referred to a help file in one of our products or read a user guide from our website? Well, that’s our team’s primary output but certainly not all encompassing of everything we develop. In general terms, we create the help that assists you in using your software. As software and technology change, so does our team. We are constantly learning and trying new ways to help you.

In this blog we hope to share with you content we’ve created, topics in technical communication, and more of the behind the scenes of being a technical communicator in the ever evolving world of software documentation.

So who are we exactly? Well we’re 11 technical writers and one manager. We’re located in three different parts of the country. The majority of us work out of our Charleston office but we have two remote writers, one in Cleveland, OH and one in Williamsburg, VA. We came to our current positions from a variety of backgrounds. Over the coming months, we’ll try to introduce ourselves individually so you can get to know us and why we’re so passionate about software technical communication and how that helps you get your job done better. And hopefully in the process, we can get to know each other a little better. We definitely look forward to hearing from you!