Crowdsourcing and APIs: Everything You Need to Know

Crowdsourcing is the act of harnessing the power and workforce of a crowd to accomplish a task. Lately, companies creating documentation for APIs have turned to crowdsourcing. Instead of companies hiring an entire documentation team, all that’s needed is one person to edit contributions. The crowd will send in the documentation and the company editor edits the submissions so they can be published alongside the APIs. The people contributing can be users or even other teams within your company. This process is appealing because it offers the advantage of the distribution of responsibilities for documentation. It also cuts down on the amount of resources a company needs to devote to creating documentation.

Becky Todd, a content manager at Atlassian (a collaboration software company), gave a talk at 2017’s Write the Docs Prauge. She describes falling into crowdsourcing management with no proper training. Her job evolved so much that she no longer described herself as a writer. She spent most of her days editing content and training contributors.

According to Todd, the key to crowdsourcing is time, but that comes after you have “identified a pool of willing volunteers with someone managing the process”. Crowdsourcing doesn’t happen on its own. It takes cultivation to grow into a proper system that can effectively produce documents.

Advantages

The knowledge of a crowd can be powerful. One person might know part of the solution to a problem and another person might know a different part. When all these different parts are combined, the crowd might figure out the entire solution. This applies to crowdsourcing documentation, as it unlocks knowledge laying unused in your user base or other parts of your company. There is something special about your user base contributing to improving a product they use that you created. Because the people creating the documentation are generally users, the content can be more targeted to what users need.

Disadvantages

While crowdsourcing can produce great results, there are some issues. Due to the distributed nature of the work, it is easy to miss things. Sometimes work doesn’t get done or is missed entirely.

Software is meant to evolve and grow; the launch version of a program will not likely be the same as the program a year down the line. Since the API that needs documentation will continue to change, the documentation needs to change too. The documentation will need to be replaced as the API changes.

The documentation being submitted is likely not coming from professional writers. It is great that people want to contribute, but the documentation needs to be done correctly. If the writing is not in the correct format with the correct technical characteristics, then it is not useful.

If you are looking to start crowdsourcing your documentation, you need a crowd. This can be hard to come by if your company is not in the spotlight. You don’t need a crowd of thousands to successfully crowdsource documentation though. It may only take a handful of experts that are willing to help. However, even large communities have a hard time getting quality content. Maybe the content the crowd produces is not useable or the crowd has no motivation to create documentation in the first place.

Make it Easy

Tom Johnson, a seasoned technical writer, and blogger, explains how important it is to make contributing easy for your crowd: “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.”

The smallest hurdle will deter people from contributing, so you want to make the process as easy as possible. If the contributing process is unclear or if the expectations aren’t properly set, then you may receive poor documentation or none at all.

Having an organized system for contributors will streamline the process and make things easier for both parties. Supply publicly available documents that lay out the process and the desired style.

Crowdsourcing can be a powerful tool. It can replace an entire hired team of writers and leave only one editor officially working for a company. There are some difficulties when it comes to crowdsourcing, especially if there is no crowd. Good systems that make it easy for the crowd to contribute help encourage people to submit content.

 

###

This article is a guest post by Nick Rojas. Nick Rojas is a business consultant and writer at Writerzone who lives in Los Angeles. He has consulted small and medium-sized enterprises for over twenty years. He has contributed articles to Visual.ly, Entrepreneur, and TechCrunch. You can follow him on Twitter @NickARojas