Search results

A Guiding Metaphor (Wikis)

Series: My journey to and from wikis

by Tom Johnson on Jun 15, 2012
categories: wikis

One of the metaphors I like to use with volunteer efforts is to compare the IT project with a service project for someone who is moving. (LDS members can relate well to this, since there's usually half a dozen moving service projects they're asked to help out with each year.)

If you've ever shown up to a moving service project and found that the person moving hasn't packed anything up, you know it's going to be a nightmare. The best moving service projects have everything already packed up in boxes, just waiting for volunteers to pick up the boxes and move them to the U-haul truck.

In contrast, if volunteers have to ask what needs to be packed, and what boxes the stuff should be packed in, you end up with a lot of volunteers standing around talking to each other rather than doing anything.

In short, with volunteer efforts, the work needs to be broken up into easy-to-understand, easy-to-finish tasks. But there can be a ton of these small tasks, because the tasks get distributed among a crowd of people.

An analogy with moving service projects: If everything is boxed up, it makes it easy for volunteers to get working in an efficient way. If nothing is packed, people will just stand around wondering what to do.

Software projects can be much the same way. If people have a clear definition of the tasks you want them to accomplish, and they have the knowledge and capability to complete them, it's likely your project and the volunteers will be successful.

Testing is a task that can be easily broken up and completed, so testing tasks usually provide a great fit for community projects. When testing tasks are clearly defined, not only can people complete testing tasks in short periods of time, the variety of roles, locations, platforms, and scenarios among volunteers provides you with diverse feedback that in-house testers can't replicate.

The Successes

For the first seven months of working with volunteers, I calculated that they contributed about 18 articles to the blog. Some of the articles were lengthy, others much shorter. The more successful articles relied on the volunteer's personal experience -- for example, the volunteer's experiences in trying to follow some goal. Other popular articles provided tips on using an application.

The number of volunteers continued to grow. At first I only had about 30 volunteers, but they increased by about 15 per month, so that within a short time, I had more than 80 volunteers, and then 90, 100+. It was hard to keep track of who was who.

At one point, I wrote all their names on paper and pinned them up on a wall of my cube. I wrote out all the topics I wanted to assign on other strips of paper (yellow strips this time) and pinned them up on another wall. I then tried to pair the two strips up (the volunteers with the topics) on a third wall.

For volunteers that successfully wrote articles, I starred their names. Eventually I separated the volunteer names into different groups, putting the active, more participating volunteers near the top of the wall.

I quickly learned that Jakob Nielsen's 90-9-1 rule was right on target: 90% of the people on any community project remain quiet lurkers; 9% contribute moderately, and 1% contribute actively.

To me, that meant if I wanted a small group of writers, I would need to recruit a large group of volunteers, more than 100.

Although many volunteers accepted assignments, I soon found it was better to try to match a volunteer's background and interests with the assigned topic. One volunteer said he knew a lot about asynchronous learning models, so I assigned the volunteer to write about this in context of community projects. Although the article needed too much editing to publish immediately, it convinced me that I needed to veer away from the paper-pin-up model of organization and start organizing the volunteer efforts electronically. That's when I started using JIRA, a bug and project tracking tool from Atlassian, to coordinate and track assignments.

I also started building out my notes for working with volunteers into a Community Project Handbook. This handbook would serve as the official guide for working with volunteers. The handbook grew to about 7,000 words and continued to evolve the more I learned.

One section was written for project managers, the other for volunteers. Project managers had to do a lot of organizing and motivating to get any project to work. There were about 5 critical steps:

  1. Get set up
  2. Define a body of work
  3. Recruit volunteers
  4. Assign volunteers to tasks
  5. Maintain regular communication

Critical to the project was the idea of personal relationships. When someone joins the project, it's important to reach out and personally welcome the volunteer. Find out about the volunteer's background and interests. This helps in figuring out what tasks to assign the volunteer. New volunteers are the freshest and most ready to contribute upon initially joining the project. After that, their enthusiasm tends to fizzle.

I developed welcome templates, which I then customized for the particular situation. Most new project members that I welcomed this way become immediate contributors. I found that at least 75% of the people I personally welcomed responded back to me, sharing more about themselves. A number of volunteers turned out to be students, not even LDS, who wanted to build their portfolios and gain some practical experience with professional writing.

One of the key breakthroughs I had was in developing a simple Microsoft Word template for volunteers to use. We had been using InDesign for quick reference guides, but I asked our department intern to convert the InDesign guides to Microsoft Word to enable customers to own the documents after we published them. One accidental outcome was to discover that volunteers could have great success with these templates.

We had a lot of success with these getting started guides. Volunteers were able to use the existing template and make a fairly good guide with little need for revision.

Several volunteers used these Word templates to create about five different quick reference guides, which I thought were all fairly high quality and which required only minimal editing. (You can download this Word template here.) I started brainstorming outlines for article templates, so that people could more or less follow a cookie-cutter approach to a blog article.

The Need for Insider Knowledge

Despite these successes with volunteers, I began to grow weary in having volunteers write articles. Most of the more popular articles on the site, I found, were articles that talked about new products and resources. Many times volunteers just didn't have the knowledge to write about these topics.

Any effort that requires insider knowledge with volunteers is much more challenging. And this is what I found to be the case with the blog and wiki. I had no trouble assigning volunteers to do writing tasks. About 75% of the people I asked to write something willingly accepted. They were more than happy to be finally assigned something to do. However, because the writing tasks often required insider knowledge, the management overhead in getting volunteers set up for success was high.

A lot of times, the knowledge you need for success is inside the firewall.

For example, let's say you need an article about Running power queries in ACME. There are a lot of advanced searches uses can do, as long as they know the syntax and key terms. You know you need to get some information from, say, Rick, the subject matter expert, about this. Now, how do you assign this writing topic to a volunteer so that he or she will be successful in completing it?

You could write a brief description of the assignment (including Rick's contact information) as a new item in JIRA, invite the volunteer to complete the assignment, and then if he or she accepts, assign him or her the item in JIRA so you can keep track of who's doing what.

However, here's where it gets hard for the volunteer. As a volunteer, you don't have the information you need. You need to contact the subject matter expert (SME) to interview him. But you're probably volunteering on your own time, after work or on the weekends – when the SME isn't available. The SME is only available during regular business hours.

You could set up a meeting, but without access to the SME's Outlook calendar, you wouldn't know when he is available. Perhaps you send an email asking for more information. But because the SME is used to working with internal people, he or she will be reluctant to reach out to an outsider with an unfamiliar email address. Volunteer requests are easy to ignore, and unless volunteers are aggressive in tracking someone down, attempts to get information are often stymied.

I've seen this kind of scenario take place again and again. If the task requires insider knowledge to complete, it's not particularly suitable for volunteers to tackle. Much documentation does in fact require insider knowledge. How is the application supposed to work? What rights and access does each role have? What is the workflow of an item through the process? It's unlikely that a volunteer will be able to figure this information out on his or her own.

Technical writers usually come to this knowledge through a series of interactions with SMEs, project meetings, and access to a development test environment (which is often behind a firewall), as well as access to test logins for various roles. If you remove all of this from the volunteer, there is little hope that the volunteer will have success in completing the assignment.

About Tom Johnson

Tom Johnson

I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.

If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.