The pros and cons of crowdsourcing your docs

By Catherine Heath on Writing docs from October 26, 2017

Crowdsourcing your docs means harnessing the power of the many to produce useful help content for your users.

Instead of having a team of documentation professionals responsible for all help content (or maybe just one person!), instead you have an editor who manages contributors.

Companies are interested in crowdsourcing because it offers the advantage of distributing responsibility for docs. It potentially cuts the amount of resource you need to devote to producing your docs.

Your contributors could be from your user base, other teams in your organization, or a mixture of both.

Becky Todd at Write the Docs

We watched a great talk on crowdsourcing docs at the last Write the Docs Prague. It was given by Becky Todd, Content Manager at collaboration software company Atlassian.

She offers a great perspective on this topic, since it’s something her company has done with their developer docs. For Becky, it’s been an interesting and relatively successful learning experience.

She describes herself as inadvertently falling into crowdsourcing with no formal training. This meant a steep learning curve, and eventually realising that she was no longer a technical ‘writer’. She was spending her days editing content and training contributors, so ‘documentarian’ became the most appealing job title.

According to Becky, the key to successful crowdsourcing is time, and that’s after you’ve “identified pool of willing volunteers with someone managing the process”.

Crowdsourcing is not usually (more on this later) something that will happen naturally, despite your best hopes, and the right process will minimize the bottleneck that you as the Content Manager can create.

She recommends not borrowing tools directly from the engineering department as they may have too much functionality for your workflow. For example, Github may be far too much for basic version control.

It’s not a ‘magic bullet’, but can reap good returns for your business.

Advantages

Unlocks knowledge latent in other parts of your organization
Enables unique contributions from the general public
Can result in documentation produced by experts in the field
Content can be more targeted to user needs

Disadvantages

There are significant advantages to crowdsourcing your docs, but the risk is ending up with documentation more like a wiki than a professional user knowledge base.

Distributed responsibility means things sometimes don’t get done
Content degrades over time and needs to be replaced
Contributors are not professional technical writers

As well-known technical writer and blogger Tom Johnson mentions, “Adding an Edit on GitHub button to my docs didn't have the immediate collaborative result I anticipated.”

The reality is that good crowdsourcing requires significant effort and investment.

Box employs a Github pull-request-like system to crowdsource their API docs from developers who are also their users. Suggested changes are reviewed and approved by the Box Developer Relations team, and they recognize their contributors for their efforts.

Let’s look at science

According to one study that explores the benefits of crowdsourcing docs for scientific software:

“Without good documentation, even the most sophisticated and efficient scientific software is difficult to use and maintain. However, due to lack of time, resources and incentives, scientists who develop software for other scientists are not keen on writing documentation.

“Scientific software packages that are freely available and shared within scientific communities often suffer from poor documentation, sometimes making them unusable.”

This is exactly the worst nightmare of a technical writer and even a product manager. But the fact is, documentation may reside outside of your professional platforms, in forums, mailing lists and in the minds of users.

The same study found that an organic crowdsourcing effort had sprung up around scientific software ecosystem NumPy, which had been notoriously difficult to understand for new users.

A key factor, though, had been securing university funding to employ a full-time technical writer to oversee the process. Though the willingness to contribute to docs can spring up naturally, the process can not oversee itself.

The necessary size of your contributor base

But what if you don’t have such an engaged community as well-known brand Atlassian or ubiquitous scientific software NumPy?

You will need to determine if you have the necessary power to crowdsource your docs. Perhaps your software doesn’t have thousands of users to tap into, but other members of your organization have specialist knowledge that they can contribute.

Many large communities have a complete lack of documentation and members have no intrinsic motivation to create any. Or, they may produce documentation that is almost as difficult to use as having none at all.

It’s not just about number of contributors but ensuring they have the depth of knowledge needed to contribute meaningfully.

Empowering your contributors

As Tom Johnson mentions, “I compared the crowdsourcing strategy to moving projects. If you put everything in boxes, each volunteer can easily grab and carry a box. But if everything isn’t already packed up in easy-to-transport boxes, the volunteers flounder.”

You’ll need to make it insanely easy for your users to contribute to your docs, because the slightest hurdle will put them off. If contributing to your docs feels too far outside their normal workflow, they’ll be far less likely to do it. If they don’t feel sure of the guidelines or parameters, this will also negatively impact motivation.

Create an organized system for users to contribute. This includes having a widget on your content pages that users can click to add comments and make suggestions. Provide publicly available documents that detail the process and style guides.

Remember, many people have anxieties about writing, especially if English is not their first language or their usual work involves barely any writing at all. Learn how to give very good feedback and enable people to accomplish their personal goals with your docs (such as gaining experience to become a technical writer).

The importance of community

‘Crowdsourcing’ should be less the focus of your efforts than building your community. If you think crowdsourcing docs is about writing, think again. It’s about building and managing a community.

To quote Tom again:

“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.”

The key is to consider exactly who you intend to crowdsource your docs from, and ensure they have the necessary writing capabilities and internal knowledge. It could be easier to crowdsource from others in your organization rather than your users. You may need to give out training to get people up to scratch.

Editing will be essential. Weigh up the amount of time it will take to manage the process versus the return you will get from crowdsourcing. If it takes you more time to manage the contributors than to write the docs yourself, it’s not worth it.