PDF version

This is a story about my journey to wikis and back again.

The Need for Shared Ownership

Several years ago, I worked in a department that produced products for senior leadership in our organization. I was the only technical writer, one of the first hired as a technical writer in fact. I used Madcap Flare exclusively to create and publish documentation in the form of online help, PDFs, and quick reference guides. I also used Adobe InDesign to create more visual, one-page quick reference guides.

I remember one day early in my employment at the organization. I had produced the first double-sided quick reference guide for the department’s flagship application. The department lead saw the guide and – according to reports related to me by others — actually became teary-eyed he was so happy. He felt he’d found someone who finally got it, someone who could create short, visual documentation that got right to the point. Perfect for executives, as well as users.

His preference for short guides encouraged me to highlight this deliverable even more, and with another project, I pitched a series of quick reference guides for each role. These guides would actually stand alone, without relying on online help as a supplement.

I meticulously created the layout and design, matching the look and feel of the application with a craftsman’s eye. The guides were works of beauty. At first I produced just four guides, one for each role, but soon I needed a couple more – an overview, and a process summary.

I handed off the PDFs to the product manager to distribute. I attended rollout pilots with user groups and watched users interact with the documentation. I refined the guides to perfection. And then one day, I got a call from a higher up office. They wanted me to send them the source files so they could own the content. No real explanation why, just a request.

Reluctantly, I packaged up the InDesign files and sent them off to the department. It was the last time I ever worked on the files. Not having the source files, I only occasionally would see a PDF from their department. They stripped out all screenshots, combined all the guides into one handbook, and changed the color scheme and typography significantly.

The application underwent additional iterations and updates. I always wondered who was updating the documentation, if at all. I was told it was being taken care of.

This experience of having documentation taken from me affected me profoundly.  I wrote about this experience in a post called, The Case of the Stolen Documentation. In many ways, I felt the other group “stole” my documentation. The project lead also felt that appropriating the source files wasn’t right.

This experience persuaded me that I needed a more collaborative model for help authoring. With a collaborative model, users wouldn’t need to steal documentation from me; instead, we could work together on updates. There would never come a day when someone would ask for the source files and then cut me out of the process. I could always have a hand in editing the content, and so could others. This was, after all, the era of Internet collaboration and web 2.0.

The Need for Constant Updates

Not only did the need for shared ownership push me away from Flare and InDesign toward wikis. Another element encouraged me in this direction as well: agile software methodology.

Agile software methodology is a method of creating software in small releases to get feedback that helps inform the next release – proceeding to build the final product little by little based on iterative feedback rather than spending two years in seclusion working from a list of requirements that are out of date once you finally release.

We released a new version of the software every month, sometimes every two weeks. As such, the documentation was continually evolving. I began to follow a more agile writing process. As I participated in training for new users, it would always surprise me that no matter how well I described tasks and processes in the documentation, users had questions. They used the application in ways I didn’t fully anticipate. Terms confused them. Step sequences were not easy to follow. They couldn’t find information. Some tasks needed to be more visible. Who could anticipate all of this beforehand? As much as I tried, the documentation always needed adjustment.

Based on the feedback from training users, I changed the documentation, making it better and better with each released version.

I even hosted my documentation on a separate server so that I could update documentation on the fly. I wrote about this in a post titled Two Stories About How to Write Help. This iterative authoring approach seemed to align perfectly with agile software methodology; it presented a fundamentally different philosophy about how to approach help.

The traditional method of help authoring is to think you can write all the help you need before the application is released. The assumption is that the writer can anticipate all the user’s concerns and needs, and so basically you’re done once you release. You can move on to another project.

In contrast, the agile writing method suggests that information should evolve following a continually iterative process. One needs to publish and get feedback, publish and get feedback, and in so doing move closer and closer to a state of documentation that is more accurate and helpful for users. This state of documentation isn’t something that one achieves on the first try, or even the second or third.

Why does documentation need to evolve continually? It comes down to limits of perspective. The idea that documentation can be produced by a single person working from a single perspective in a single department is a flawed idea. Only overly confident technical writers blinded by their insider’s perspective would think this way. You have to carefully monitor feedback from multiple perspectives and make updates over a period of time post-release. I wrote about this in a post titled, A Reverse Approach to Documentation. With the initial release, you include only a bare-bones set of documentation. As soon as you begin alpha testing, you listen carefully to user feedback and problem areas, and that’s when you focus your energy with the documentation.

These two trending needs – the need for collaboration, and the need to make constant updates to documentation – persuaded me that I needed to adopt a different method for help authoring. Using a help authoring tool to produce static files that only I could edit felt like a dated authoring methodology that would ultimately become a thing of the past. I needed to adopt a method that was more dynamic. With this, I decided to move from Flare and InDesign to wikis.

Some Wiki Basics

Those are the two forces that brought me to wikis: the need for shared ownership of content, and the need for constant updates based on evolving information. Wikis seemed like the perfect platform for this new approach.

There are more than 100 types of wikis (see the wiki matrix), though only a handful are worth considering. Confluence is probably the wiki most suited to documentation purposes, but our organization already had a couple of wiki platforms available: SharePoint and Mediawiki. (SharePoint for internal infrastructure, Mediawiki for community collaboration.) I’ve tried both, and each has its advantages and disadvantages.

Regardless of the wiki platform, most wikis more or less have a similar set of features. I’ll talk briefly about a dozen wiki features in the context of Mediawiki, which is the same wiki platform that Wikipedia runs on. Mediawiki is open source wiki software, and widely used across the Internet. You can install Mediawiki yourself in about five minutes.

When you work with wikis, here are some things you’ll find different from authoring with regular help authoring tools:

• Content ownership
• User pages
• Authoritative content
• Recent Changes
• Discussion Pages
• Everything on One Site
• Wiki Syntax
• Translation
• Content re-use
• Managing Content
• Categories

I’ll briefly explain each of these features before diving into the more important topic of community collaboration.

Content Ownership

No one truly owns the content on a wiki. Typically you “watch” pages that you’re interested in. For example, if you published documentation on the ACME widget, you would most likely watch all of the ACME widget pages. If someone makes a change you don’t like, you can undo the change.

Some wikis have a built-in workflow that forces revisions into a review state before the edits are live. However, most wikis try to avoid this publishing bottleneck and work on a model of trust. Most of the time, the edits are beneficial so we allow them by default. No one owns the content, so no one should enforce restrictions on editing the content.

Community ownership sounds ideal, but it has some drawbacks. Mainly, it’s easy for someone to create pages based on a current need, and then completely neglect the page when updates are needed. For example, let’s say you currently have a project and you need to get some information out about it for others who are participating. The wiki works great for this, as it allows quick and easy publishing. It’s almost an adrenaline rush to see your content published so quickly. Everyone can access and edit it, and it seems like a winning situation all around.

Then the project ends, and you no longer have a need for the content. Rather than go through and delete the content, as well as any links pointing into the content, it’s much easier to simply abandon those wiki pages, because after all, you don’t specifically own them anymore; they’re on a wiki, so the community owns them.

For example, a few years ago I wrote a lengthy quick start guide for WordPress. I published it on the WordPress Codex here: WordPress Quick Start Guide.

Who actually owns the content? Although I originally wrote it, I contributed it with a Creative Commons license so I no longer own it. At first, it was cool to see my content available in a public setting. I didn’t need to get any permission ahead of time. It was just up and available as soon as I published the page.

But then WordPress came out with a new version, and another new version. I didn’t bother to update the original content to match the later versions of WordPress. Eventually the content became out of date. Some people edited some parts of my WordPress Quick Start Guide, but with no one really invested in it, with no true ownership of the content, no one felt a responsibility to update all the content to keep it current.

The lack of ownership can lead to many wiki pages being out of date. Many times a wiki has so many pages, it’s hard to tell who authored what, and whether the pages are still needed, or whether they’re up to date.

Although community ownership is a neat ideal, ultimately each wiki should have a chief content owner, someone who is dedicated to the site as a whole and keeps a close eye on all the content assets. Without dedicated managers to review and update the content, wikis can quickly expand into bloated, outdated content messes.

On the flip side, when the community owns the content, community members can also keep content up to date when the original author flounders. Many times the original author isn’t aware of all the places that content is out of date. As community members use the documentation, they often find places that need updating. Because the content is on a wiki, they can quickly and easily make these updates.

Withdrawing from tight control and ownership is a hard transition for many to make. One of the writers in another department at my work uses our wiki to publish some documentation. At the top of the documentation he added a note asking that no one delete or edit the content on the page, since it’s official documentation.

I think he doesn’t really agree with the underlying philosophy of a wiki. That philosophy is this: When you publish content on a wiki, it no longer belongs to you. It belongs to the community. Others can update the content as much as they want, without feeling that they are infringing on your content. It’s not as if others are opening a file on your computer and making unsolicited edits. Instead, the content is owned by everyone, and everyone has a right to edit it.

User Pages

Because everyone can be making edits, it’s important to track who makes edits to which pages and when. With Mediawiki, each user has a “user page.” When you make an edit, the page has a version history showing the user names of each user who made changes to the page. Each user name links to the user page.

Go to any Wikipedia page (such as the Technical communication page) and click the View history link. You will see a list of all the users who made changes to the page. If the user doesn’t have a user page (because the user never logged in and created an account), the version history shows the user’s IP address. You can usually click the user page to read a little bit more about the user.

From the user page on a Mediawiki site, click the User contributions link in the sidebar to see other edits the user has made on the wiki. You can also click the E-mail this user link to send an e-mail to the user through the wiki interface.

A lot of times, if you’re unsure about the edits someone is making, you can assess the person’s authority and credibility from his or her user page. The history of a page also lays bare all the people who contributed to the content, so you can read about the people who shaped the page’s information.

As you look through the history of a page, you can see how many characters someone added or removed. A lot of times, edits are trivial, correcting a misspelled word or adding a missing word. When you see that someone has added 1,000 characters or more, the edits are more significant. In my experience, 90% of the edits are minor, such as adding a comma or capitalizing a word. Rarely do people make extensive edits. Writing is a lot of work, after all.

Authoritative Content

As I’ve worked with project managers to sell them on the idea of a wiki for documentation, many balk at the idea of giving users the ability to edit content. They feel users might introduce errors, communicate points poorly, and in general lower the authoritative quality of the content.

I’ve heard some users ask how they can know what content is official and what content originates from the community. With wikis, users may be left to wonder about the source of policies, procedures, and other material. Do they come from the company, or other users? Companies give up some of this authority when they move to a wiki.

The lack of authority may or may not be a big deal. It depends more on your product. If you’re a pharmaceutical company, where you could be held liable for the information on your site, a wiki is probably not the way to go. And if you’re a financial company or in some other regulated industry that must maintain tight control over the information, you probably need a more secure, authoritative method for maintaining and publishing your content.

However, in many cases, users are accustomed to getting information from other users. Users often resort to google to search for how-to information anyway rather than looking at the authoritative content published by the company. Ultimately, with instructional content, the source does not so much matter as much as the accuracy of the content. As a user reads and acts on the material, if it’s inaccurate or confusing, it doesn’t matter who it’s from. Users are more interested in simple, relevant instructions that speak to their specific situation.

Recent Changes

Remember that wikis are in a constant state of flux. You hope that the information continues to evolve into a more and more accurate, thorough, helpful state. So after you publish content, you’re not simply done with the content. Instead, you must keep an eye on the changes. You usually do this by regularly checking the Recent changes.

If you go to a Wikipedia and click the Recent changes link in the sidebar, you can see all the changes taking place on the wiki. The rate of change on Wikipedia is pretty astounding, with thousands of changes taking place each day. The number of changes you see is proportional to the size of your wiki and the activity of your community.

On our organization’s wiki of about 1,000 pages, we typically see about 15 to 20 edits a day, usually from 3 to 4 different people. You can monitor the recent changes through an RSS feed, or you can even set up alerts to be notified of every single change that takes place on the wiki.

When you come into work in the morning, just as you check your e-mail, you also check the Recent Changes. It is somewhat astonishing to see changes take place in seemingly random ways on a large variety of pages. People are out there at all hours of the day, reading your content and making updates when you least expect it.

Each page has a detailed version history, so when you see a change, you typically compare the previous version with the new version to see what has changed. Users are prompted to write a summary of their changes to speed this content review. For example, a user might note that he or she added some punctuation, or clarified a section. If you know and trust the user, you can probably just assume that the edit is a beneficial one without reviewing it closely.

However, if the change is made by a user you don’t know, you will want to carefully compare the new version with the old to evaluate the change.

I have only encountered one case of wiki vandalism, in which the user clearly made malicious edits. Mediawiki has an extension called Nuke that allows you to mass delete a user’s contributions. If someone is vandalizing the wiki, administrators can undo all edits from that user as well as block that user from making any more edits on the site.

Talk Pages

Many times readers don’t want to make direct edits. Instead, they want to ask a question or make a comment about the content. As a companion to every page on Mediawiki sites, there’s a Talk page where you can ask questions, raise issues, and otherwise carry on a discussion about the content on the page.

The Talk page functions similar to a comments section, but it allows users to carry on this conversation on an entirely separate page that won’t elongate the original article.

The Talk pages aren’t usually familiar to many mainstream users. Many more users are familiar with comments sections below the pages. But the Talk page is really more appropriate on a wiki, because you’re not merely making a comment; often the Talk page reflects proposed edits, stated reasons for changes, or other analysis of the content from a contributor’s perspective.

Sometimes the Talk pages are more interesting than the actual article pages, because it’s on the Talk pages where users share their opinions in a more candid, straightforward way. Does the article seem biased? Does it need to be broken up? Do the assertions need references? Do the instructions not work?

You may wonder whether all of this discussion clogs up the search results for the site. Not so. Mediawiki gets around this through the concept of spaces. Articles are in the Main namespace, which is the default space that searches look in. But if you select the Talk space check box on your search results, the results will expand to include Talk pages in the results as well. There are other spaces where content resides as well (a file space, a help space, and more).

Regardless of the idea of spaces, when Google indexes your site, Google completely ignores the separation of talk pages from article pages and mixes everything into one big list of results.

Everything on One Site

Although Mediawiki may separate content through the idea of spaces, most articles will still be in the Main namespace. This presents another shift in content organization that may be new to technical writers. With a traditional help authoring tool, such as Flare, you create a project for a software application and put all the help topics in that project. When you’re done, you publish the help files for that application in its own webhelp output. Searches in the content are restricted to the single product contained in the webhelp.

Not so with a wiki. A wiki is a website, and just as you don’t create a new website every time you need to publish a set of articles, you also do not create a separate wiki every time you want to add pages for a new product. In my organization’s wiki, we have help materials for about least two dozen products on the same site. If you search for something generic, like “Editing settings,” good luck on finding anything in the results. At the very least, you must make sure you add the product name in your searches.

There are benefits to having everything on the same site. Let’s say you’re a developer and you want to stay on top of all the changes made for a lot of different products across the organization. By monitoring the Recent Changes section of a wiki, you can keep abreast of all the changes in a way that would be nearly impossible with a webhelp output from a help authoring tool. In this way, keeping everything together on the same site provides a unique advantage that other platforms can’t offer: integrated awareness.

You can also cross-link one product to another more easily. If you have a lot of products all in the same family, having all the help material mixed together on the same site might be a good idea. You can help users find information about other products as they read information about one product.

However, having all product information on one site also has its downsides. The nature of wikis is to grow indefinitely. The more content you add, the more your search results get diluted. If it’s unlikely that users interested in one product would search for another product, separating the content into different sites may provide better findability.

Another downside is that, if everything is one site, branding content for different products in Mediawiki is not possible. For example, if you have one category for Product A, you can’t customize the wiki skin to match product A, yet make the skin look different for Product B. (You can, however, do this in Confluence.)

For some product managers, customizing the help’s skin is important so that the user experience feels seamless between the application and help material. You can, of course, customize the overall Mediawiki skin. Just realize that customizing a wiki skin is not an easy task (at least with Mediawiki it isn’t). I create a lot of custom WordPress sites. I’m familiar working with PHP code and CSS. But Mediawiki’s code is harder to understand. It runs on PHP as well, but the PHP tags aren’t as clear and well-defined as with WordPress.

I spent about a week creating a new skin for Mediawiki, because the upgrade from 1.15 to 1.19 completely broke the existing skin. We finally upgraded the skin, but had to involve some developers and interaction designers to work out a few kinks I couldn’t figure out.

Wiki Syntax

Although wikis usually rely on standard CSS for their display in the browser, almost every wiki has its own custom syntax of asterisks, back ticks, brackets, and braces to format content. The idea is that wikis simplify publishing by not requiring users to know HTML. Instead of creating a bulleted list like this:

<ul>

<li>first item</li>

<li>second item</li>

<li>third item</li>

</ul>

You just create the list by adding

* first item

* second item

* third item

It gets pretty easy to do basic formatting with wiki syntax. Instead of coding a link as <a href=”http://google.com”>Google</a>, you simply write [google.com Google]. Tables are a little more complicated, but nothing too complex. (They involve pipes mixed with brackets.)

When you save the page, the wiki syntax dynamically converts to HTML so that the formatting renders correctly in the browser. Viewing the page in the browser, you could view and copy the source code, and you wouldn’t see any of the wiki syntax. You would just see HTML.

Despite the simplicity of wiki syntax, many end users feel intimidated by the syntax. Mainstream users prefer a WYSIWYG interface. There are several WYSIWYG extensions for Mediawiki, but they invariably introduce syntax errors that frustrate more advanced users.

Here’s one more interesting characteristic of wikis: wiki syntax is nonstandard. The syntax for one wiki differs for the syntax with another wiki, so when you switch wikis, you have to learn the new wiki’s world of syntax.

The idea of wiki syntax is to allow the masses to contribute, rather than limiting web publishing to the developers and techies. As such, wiki syntax attempts to be simple and learnable. But the instant you want a more sophisticated format and layout, wiki syntax can become more tricky than merely hand-coding. To get around this, sometimes wikis actually allow you to mix wiki syntax with HTML.

Translation

At least with Mediawiki, the custom syntax used on wikis poses some problems for translation. Usually help authoring tools will export content in an XML format that translation memory systems can process (exporting and then importing the XML). However, with Mediawiki, if you export all the content in a category, the export mixes XML with wiki syntax. This means the exported content will include syntax that includes * and # and ‘ and [] and {}. (With Confluence, I believe the export is pure XML.)

Now, Mediawiki may be a poor wiki to use for documentation. Mediawiki isn’t meant for technical documentation but rather as an encyclopedia, and Wikipedia’s translation strategy doesn’t involve exporting the content to a translation system and then reimporting it.

Instead, with Wikipedia, each translated site is an entirely different version. The English and Spanish and Portuguese Wikipedia sites do not have a commensurate number of pages. An article in Spanish may be half as long as the same entry in English, if the article exists at all. The translated sites are other members of a wiki family, rather than translated versions of the English wiki.

Not all wikis handle translation as wiki families. Actually, it’s more common among Mediawiki sites to see a series of subpages showing the translated pages. For example, below the English Mediawiki page, you may see a list of other languages. The articles in the other languages would be translated, but not the overall wiki interface.

If translation is a strong requirement, you might want to think about a platform other than wikis. Even if you do manage to translate the wiki content, you run into several other issues after the translation. When users make edits in other languages, how will you review and evaluate the changes? You will likely need a language lead for each language you translate to. The language lead can evaluate the changes to decide whether they’re beneficial or not.

Also, if you translate the template names and the category names, managing the wiki becomes more difficult. If you don’t translate the template names or category names, you limit the ability of community users in other languages to manage and administer the wiki. But if you do translate all of these files, you impair your own ability to manage the wikis in other languages.

Finally, because wikis are meant for continuously evolving information, you will need to decide how often you propagate the changes through to the other languages. Will you immediately translate each and every change made on the English wiki to your other language wikis? Or will you make an effort to update the translations on a quarterly basis? Will it bother you to have some content that is out of sync in different languages? And what happens when you have some proactive community volunteers update some of the pages but not others — how will you keep track of what has been updated and what hasn’t? In sum, translation poses a substantial new layer to consider with wikis.

Content Re-use

Another common feature that technical writers need in publishing help material is the ability to re-use content. If you having a common series of steps that preface a lot of different tasks, such as how to access a Settings panel, you usually want to re-use this language so that you reduce translation costs. If you have 10 different variations in the way you say the steps, you end up translating 10 times the content. You also increase your own workload considerably. Content re-use can help you avoid this.

On Mediawiki, you can re-use content, but the content re-use features are not as easy as they are with a help authoring tool. With Mediawiki, the way you re-use content is through templates. You create a template, and then you insert that template into any page. You can change the template and your changes will be reflected in all the places the template is inserted. You can also see all the pages that the template is inserted in.

Templates are how you create sidebar navigation as well. By default, wikis are usually flat. They don’t have the tree-like table of contents on the left (well, Confluence does; Mediawiki and many other wikis do not). As a result, if you want to provide an easy navigation system for users, you have to create a template, and then update that template each time you alter the navigation.

At best, the ability to re-use content on Mediawiki is somewhat rudimentary.

Managing Content

With a help authoring tool, you often manage your content in various folders and tools, or you have an administrative interface that you access to manage content. With Mediawiki, you don’t have an administrative interface. The browser itself is the interface.

Let’s say, for example, that you want to see all the templates that you’ve created. You search for special:templates in the wiki’s search bar and the results show a list of the first 50 templates in your wiki. If you want to see all your categories, you search for special:categories. To see all pages, you can search for special:allpages.

You can manage content by doing a variety of queries like this. You can see the longest pages, shortest pages, orphaned pages, most popular pages, unused templates, unused categories, unwatched pages, a file list, and so on. You can run these queries because the wiki content is stored in a database. There’s also a page on the wiki containing links to each of these queries.

Managing the content through the interface is a little uncomfortable if you don’t know everything you can access. A lot of times I’ve run across a query (like special:ancientpages) and thought, hey, I didn’t know I could do that. With a help authoring tool, you can often look at the various buttons and menus and browse what you don’t know. But if you don’t even see something that looks unfamiliar, it’s less likely that you’ll start exploring it.

That said, it’s rewarding to be working so regularly in the web browser. One of the shortcomings of help authoring tools is their distance from the web. The outputs from help authoring tools often feel a bit like they belong in the pre-Internet era. Before Flare’s HTML5 skin output, most webhelp skins from help authoring tools looked rather dated. With wikis, you’re working in a browser and the display is entirely browser-based. Wiki sites look much more web-like.

Categories

Finally, I’ll cover one last unique feature of wikis: categories. Categories aren’t that unique, but Mediawiki implements them in a way that technical writers may find unfamiliar. At the most common level, you add all pages to a category that you want grouped together. With a help authoring tool, you would group similar pages into the same folder. However, with a wiki, because wikis are a flat system, without the nested hierarchy that you find in a table of contents, categories provide the default system of navigation.

You can have categories and sub-categories and sub-subcategories. That may seem somewhat normal. But here’s the interesting thing with Mediawiki: all categories must have a parent category that becomes more and more general until you reach the highest level of abstraction. The categories form a complete hierarchy of classification.

This category hierarchy can be somewhat amusing. For fun, visit any Wikipedia page, scroll to the bottom, and then start browsing up the parent categories. Here’s the upward path when you start at the Technical Communication Wikipedia page.

You may have missed the category feature on Wikipedia because categories aren’t that useful. In fact, if they’re intended as a navigation aid, they’re almost invisible, buried at the very bottom of the page. No doubt their demotion in the visual hierarchy of the page has something to do with their uselessness as a method for finding content.

Instead of using categories to navigate content, wikis often rely on cross-linking within topics. And this turns out to be one major advantage to wikis. Because all the content is on the same site, there are many more opportunities for cross-linking. Wikipedia has so many cross-links, or internal links, meaning links from one Wikipedia page to another, that all of these links add a tremendous SEO influence with Google’s search engine. You can see this influence each time you search in Google. Wikipedia pages almost always rank near the top.

Community and Collaboration

I’ve explained the most salient characteristics of wikis that will be of interest to technical writers. However, these are mostly tool-related characteristics. If you’re the only person publishing to a wiki, there’s little reason to actually use a wiki as a platform. The whole point in using a wiki is to capitalize on community and collaboration. This is the harder part of working with wikis, and it is what I will address now.

The potential reward in collaborating with the masses is an idea that shouldn’t be underestimated. Almost everything interesting happening on the web comes about through community. Think of any well-known site. Its innovation isn’t the technical features of the platform but rather the community. Wikipedia’s genius is the collective contributions of so many different people working on an encyclopedia of all human knowledge. YouTube is a collection of community-contributed videos on virtually every subject. Twitter, Facebook, Linkedin, Craigslist, Pinterest – you name it, all of these sites are popular because of the community, not because of their site design or functionality.

Given that amazing things can happen through community and collaboration, it seems natural to adopt a similar model for documentation. Even on a small scale, if users can contribute just a small fraction of the content they contribute on these popular sites, wouldn’t the endeavor be worth it? Certainly. But the real question is how you build a thriving, contributing community.

Spontaneous versus Directed Edits

One of the first questions to address is how much autonomy you will give to community members. Will you allow them to do anything they want, or will you restrict their contributions to only those actions your company decides to allow?

Giving community members a lot of autonomy can increase their motivation to get involved. For example, with WordPress, a lot of community plugin developers have an itch they want to scratch, so they create plugins to satisfy specific needs they have. That’s their motivation. But you may not want your community members creating code that strays outside of your company’s direction.

When it comes to content, community members are usually less enthusiastic. If you simply include the ability for community members to edit content, but you don’t direct or guide their efforts in any way, chances are they will not make a lot of spontaneous edits without some overriding collaborative purpose. Just adding an edit button in your documentation does little. In fact, I think many people give up on wikis when they find that almost no one edits the content.

If you want community members to more actively write and edit content, you may need to provide more direction. In a presentation at the STC Summit, Sarah Maddox explained that at Atlassian, they do regular doc sprints in which they carefully list out all the topics they need content written about, and then they make a request for people to write those topics. She said that it takes a lot of preparation to identify the topics, but the sprints are relatively successful.

Doc sprints are a popular method for getting community together to write content. I admit that I’ve never done a doc sprint. I have other methods for interacting with community.

The Wiki I Work With

The primary site I work with is LDSTech. LDSTech has a wiki, blog, and forum. One of the site’s purposes is to allow community members to contribute their time and talents. LDSTech is a technology site for the LDS Church, so the community members are mostly LDS (Mormon).

According to a recent study, LDS church members contribute about 35 hours per month toward volunteer callings and other efforts. (Yes, that’s about eight hours a week!) Providing a community where the more technical members could contribute using their writing and IT talent seems like a natural fit for such a volunteer-oriented community.

The LDSTech site has about 30 different projects that members can get involved in. Most of these projects do not involve writing. Rather, they involve beta testing applications, participating in design brainstorms, developing code for technical solutions, and other technical efforts.

I decided to create a project that would allow community writers to write for both the LDSTech blog and wiki. When a volunteer wants to get involved in a project, he or she navigates to the project page and clicks a Join button. His or her name is then added to the list of other project participants, and the project manager is notified that there’s a new member.

Project managers can reach out to the new member and welcome him or her, and then assign a role to the volunteer (such as tester, writer, developer, project manager, database engineer, security engineer, or writer).

On average, there are about 100 volunteers on each of the projects, including the project to write for the blog and wiki. Many community members are interested and willing to help out. Figuring out work for everyone to do is actually the hard part.

To coordinate tasks, I use JIRA, a project and issue tracking tool from Atlassian. New members joining the project are automatically added to the project’s JIRA instance as well as to a Google Group, which acts as a listserv for communication.

We use the blog to continually attract new members to the community. Overall, the model works pretty well. People interested in technology read the articles on the blog, which then presents them with opportunities to get involved in community projects. We don’t have a problem in attracting more volunteers to join the community. The problem really is in figuring out the tasks to assign to volunteers.

A Guiding Metaphor

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.

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.

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.

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.

Writing Is Harder Than Most Think

Another challenge in engaging volunteer writers is that so many people overestimate their writing abilities. Certainly writing skills can be measured on a spectrum, with varying levels of competence. Earning an A from a high school English class may inspire someone with confidence that they can write, but their writing skills may be more tailored to a specific situation that does not match the assignment at hand.

Technical writing usually follows a meticulously detailed, step-by-step procedural approach. You likely have a style guide and general methodology that you follow. Volunteers who try to jump into technical writing tasks usually don’t have this background.

Even with blog articles, I haven’t had many volunteers who can simply write an article that requires little editing. Many people have expectations about blogging that are much lower than our organization’s publishing standards. Because it’s a blog, suddenly their writing voice becomes unnaturally informal, the organization less structured, and the ideas less developed.

When a volunteer submits a draft that needs a lot of work, it poses a challenge for the project leaders. Do you scrap an article that requires too much editing, even at the risk of offending the volunteer? Do you try to salvage the article by heavily rewriting it? Do you thank the volunteer for his or her efforts and then sit indefinitely on the article, shelving it unpublished?

I have tried all of the above. While at times I’ve been impressed by content that volunteers write, all too often the content requires too much editing and rework to make the effort worth it. Many times volunteers who participate on writing projects are looking for opportunities to improve their writing. Many professional writers simply aren’t interested in volunteering writing in their own time.

In addition to writing articles, I have also tried giving articles to volunteers to edit. One person suggested that I rotate articles through a series of volunteer edits, hopefully ratcheting up the quality with each volunteer edit.

I have tried this, and many of the edits usually are light proofreads, corrected misspellings here and there. They fix grammar in places, but never really address higher order concerns of organization, ideas, accuracy, and other more significant content matters.

Do You Really Need a Wiki for Volunteers?

At one time I thought that if collaboration with the community were a high priority, then I needed to use a wiki as a collaborative platform. How could I engage in collaborative efforts without a wiki?

Although this seems logical, it turns out that a wiki is not necessary for collaboration. Many volunteers who write articles are uncomfortable publishing them directly on the wiki. They prefer to write in Microsoft Word and upload the articles to Dropbox or JIRA.

If you want volunteers to publish content directly on the wiki, you will need to teach them wiki syntax. Given all the work you usually do to provide feedback on the content and shepherd and article through successive edits, holding a volunteer’s hand as he or she learns wiki syntax (and then correcting their wiki syntax errors) usually turns out to be more overhead than it’s worth. It’s easier to simply publish the article for the volunteer instead.

When I started to realize that wikis weren’t a necessary platform for interacting with volunteers, I started to rethink the wiki as a platform. You can have a lot of success with community and collaboration without using a wiki at all. In fact, because the content is not being published live, for the whole world to see and immediately interact with, volunteers actually feel more comfortable contributing.

Now, I’m not saying this is the case for all community efforts. Certainly large-scale efforts like Wikipedia run on a model that is entirely wiki-based, from the recruiting to the coordinating of assignments to the publishing. But in my experience, that kind of natural interaction will not arise without a strong guiding self-interest in the volunteers.

With WordPress, many volunteers have this self-guiding interest because they’re building a plugin to fit their needs. With Wikipedia, a subject matter expert may have a reason for shaping information about a topic he or she is expert about. With Youtube, contributors aren’t uploading videos out of any desire to create a library of video content. Usually they just need a platform to publish their videos.

When volunteers don’t have a strong personal motive for engaging in the work, but are rather volunteering for more altruistic motives, you need to provide more direct guidance and encouragement in the volunteer process. You need to make it as easy and comfortable for them as possible to contribute.

Turning Point

I tried the volunteer writing model for more than a year. I kept thinking that if I just figured out the right approach, it could take off into endless productivity. With 100+ writers creating content on a regular basis, we could publish new blog posts daily. We could translate documentation overnight. We could sketch out a skeleton of tasks to write about, and then have volunteers fill in the details. It didn’t happen.

The reasons, as I have stated, can be summarized in three bullet points:

• Writing requires insider knowledge that volunteers lack.
• Professional writing standards are usually beyond volunteer capabilities.
• The management overhead in coordinating volunteer writing barely outperforms the return.

This marked a turning point for me in using wikis as a collaborative platform.

With wikis, I did like the publishing immediacy and the web interface, but Mediawiki had so many shortcomings that the platform didn’t seem worth it without having an overwhelming need to collaborate.

With Mediawiki, I couldn’t publish to any other output other than web. With Flare and other help authoring tools, you can publish to PDF, Webhelp, EPUB, Mobile, and more. Given the proliferation of mobile and tablet devices, it seems that technical writers will need to master multi-device publishing if they are to remain relevant. With that, I switched back to help authoring tools and wrote a post, When Wikis Succeed and Fail.
Switching back from wikis to traditional help authoring tools

Time for Another Model: Testing Documentation

Despite my apparent failure with wikis and engaging volunteer efforts, I have not thrown in the towel on volunteer efforts. I do think another model may be more productive: crowdsource documentation testing.

Our biggest success in LDSTech by far has been with testing rather than development. Testing a software application across the variety of platforms (iOS, Android, BlackBerry, Windows), carriers (AT&T, Verizon, T-Mobile), locations (North America, Europe, Africa, South America), roles (clerks, bishops, stake presidents, auxiliary leaders, members, website administrators), computers (PC, Mac, other), operating systems (Windows 7, Windows 98, Mac OS, Linux), browsers (Opera, Safari, Chrome, Firefox, Internet Explorer 6,7,8,9), and scenarios (so many possibilities) is pretty much impossible to do in-house.

The in-house quality assurance team can test general load and general requirements for the software, but testing all of the possibilities of user experience proves impossible under normal budgets.

Because of the success with testing, our team decided to build a tool that would facilitate more directed testing. The tool was just released a couple of weeks ago, and it’s still very new. But here’s how it works. The testing lead enters a list of specific test cases he or she wants the crowd to test. Users can respond to the test cases with pass/fail options. If the user marks the test case as fail, he or she is prompted for a reason why. The failed responses are automatically appended to JIRA items.

When multiple volunteers report a failure for the same test case, the failures are appended to the same JIRA item, thus removing the chaotic mess in the forums where responses about bugs appear across a variety of threads.

The tool was designed for testers to test software functionality, but it also works with documentation (documentation is, after all, part of the product). Each task functions similarly as a test case in software. If users cannot complete the documentation’s steps, they can mark the task as fail and explain why.

For the following reasons, testing documentation may prove to be the biggest win for writing within the community:

• Testing documentation does not require insider knowledge.
• Testing documentation does not require professional writing skills.
• Testing documentation does not require a lot of time from volunteers.

Additionally, through the crowdsource testing tool, which we call Swarm Tester, the feedback can be neatly organized.

First Experiences with CrowdSource Testing

Although it’s still too early to tell, my experience with crowdsource documentation testing has been positive. I am getting just the kind of feedback that I truly want. With one of the applications we have help for, I created a link to each individual task. The application was rather light, so I just created about 25 links. The test cases outlined that people should test the steps in the documentation. If tasks did not have steps, users were to test the clarity of the information.

It’s only been about a week using this model, but so far I’ve found that many participants who didn’t write articles did in fact participate in reviewing the documentation. Their comments were helpful and on target. I hadn’t updated the application’s help for about a year, so there were clearly some parts that were out of date.

Interestingly, one team member decided to simply update the inaccurate information directly on the wiki, because, after all, it was editable. Most of the others, however, made recommendations for changes. Within a week, about six different volunteers tested the documentation in ways that proved very helpful.

Rather than struggling to edit a volunteer-written article, or figure out a topic that volunteers could successfully write about, or figure out how to connect the volunteer with the right information, I could focus volunteer efforts on well-defined tasks that didn’t require any writing or knowledge. All they had to do is try the task and provide feedback. It was perfect.

Some Limitations with Crowdsource Testing

There are a few complications with crowdsource testing. For starters, not everyone can test every role. Unless you can supply sample roles for users to log in and use, some users may not be able to test functionality because their role lacks the appropriate rights.

Another complication is that directed testing removes the spontaneous exploration and discovery that users might have in browsing an application. By specifying all the cases we want users to test, we may overlook the many cases that users don’t test because we put figurative blinders on the users. Failed reports will only give feedback about identified tasks, not those tasks that users do but which do not appear in the help.

Finally, using a crowdsource testing tool does not leverage the writing capabilities of the crowd. Anyone can test a task or procedure without leveraging any particular writing talent at all. In that case, it’s not capitalizing on writing at all.

Even with these complications, I feel that I have hit the sweet spot in leveraging community contributions with documentation.

Conclusion

As you can see, I have moved from using a traditional help authoring tool and writing alone to a more collaborative authoring environment based on a wiki platform. Despite my attempts at getting volunteers and others to write, the efforts largely stagnated and weren’t worth the management overhead. Because collaborative writing failed, I didn’t see any need to continue using wikis as a platform, since help authoring tools could provide more robust outputs in different formats.

However, rather than abandon community and collaboration altogether, I instead moved toward crowdsource testing of documentation, which proved to be more useful because it does not require volunteers to have professional writing skills, and it simplifies the tasks to complete as well as the time involved.

I think wikis could still be useful in some collaborative situations, but unless each of the collaborators truly has the ability to collaborate on the writing tasks, the wiki platform doesn’t ultimately help the overall goal.

I do feel optimistic about crowdsouce documentation testing, but even this model needs to go a step further. Rather than having volunteers log into separate tools to test a task’s accuracy, the pass/fail test should be integrated directly in each help topic and run on a continual basis. Each time a user reads and follows the help in a real situation, the user should be able to pass or fail the documentation — based on his or her real-world need. If failed, a JIRA item should be automatically created for the writing team to address.

When the writing team resolves and closes out the JIRA item, the user receives a notification that the documentation has been updated. This notification helps the user know that reporting a failure helped improve the documentation. The user’s effort was not unrecognized, and through his or her feedback, the documentation has become more usable for others.

The overall model is still collaborative, but the collaboration does not rely on end-users writing documentation.