I.T. Discussion Community!
-Collapse +Expand
Tech Writer
Search Tech Writer Group:

Advanced
-Collapse +Expand Tech Writer Store

Prestwood eMagazine

October Edition
Subscribe now! It's Free!
Enter your email:

   ► KBRole-Based T...Technical Wr...     Print This   
Go To Random Article
  From the November 2014 Issue of Prestwood eMag
 
Tech Writer Technical Writing:
Crowd-Sourcing API Documentation
 
Posted 46 months ago on 12/20/2010
Take Away:

Crowd-sourcing (that is, using Web-based technology to gather API documentation content from your users) has the potential to lower documentation costs and make your documentation more relevant. However, relying solely your developer community to provide documentation will result in uneven quality and coverage. I recommend a hybrid approach, where professional programmer/writers write parts of the documentation, as well as rewrite and polish content from the community. Several tools are available that enable communities to contribute documentation content. 

KB102203



Introduction


During economic hard times, budgets are being cut everywhere, and that includes budgets for creating API documentation. Web2.0 technology now allows your users to contribute information about how to use your platform, a concept sometimes called "crowd-sourcing". One could imagine that crowd-sourcing can reduce, and possibly even eliminate, the need for programmer/writers to document APIs.


Is this a recipe for leveraging technology to lower your costs, or a recipe for creating unusable documentation? This concept is very new, and it's too early to reach a conclusion for certain. However, I believe that the answer lies somewhere in between, and if properly managed, crowd-sourcing can both lower your costs and improve the quality of your documentation.

The Risks of Crowd-Sourcing


It doesn't take much experience in the software industry to realize that it's rare to find people who program well and write well. What are the odds that your users will have both of these skills? Even if they do, what are the odds that they are willing to contribute well-written documentation for free? You cannot simply create a public forum and expect the quality of writing to be anywhere near what you can get by paying a good programmer/writer.


In addition, if you are not paying your writers, then they will write about whatever interests them. You will end up with very uneven coverage of your platform. Expect to see mostly tutorials and sample code from your community, and very little in the way of API references and overviews.

The Advantages of Using Your Community


I often compare APIs and API documentation to a user interface. Just like a user interface, the easier an API is to understand, the more likely developers are to adopt and use your platform. A common problem with software applications is that they are created without a true understanding of what users want. The same applies to software platforms: API documentation often does not explain what users really want to know.


The advantage of crowd-sourced documentation is that it is much more likely to cover the topics of interest to users. People will write about how they are using the API, and often companies will discover that their software is used in ways that they did not even anticipate.


Of course, not paying the writers is also an advantage. But, in the end, you will only save money if your documentation does not lose quality. Once you lose quality, then you are at risk of losing customers or increasing the cost of technical support, which will easily outweigh the cost of writing.

Taking a Hybrid Approach


The logical way to get both the advantages and to avoid the disadvantages is to take a hybrid approach that involves both community content and professional programmer/writers. I recommend four strategies that you could use.

  1. Divide up the work. Hire a programmer/writer to write the sections that the community is unlikely to write, such as high level overviews and reference topics. Then make it easy for the community to contribute tutorials and sample code.
  2. Community writes, programmer/writer rewrites. Raw content from community developers is not going to be as well-written as content from a programmer/writer. However, a programmer/writer can take the content and rewrite it much faster than if he or she had to create it from scratch.
  3. Provide structure. Rather than providing an empty Wiki, create an outline or stub topics as a way to provide ideas for people to write about. This will increase the chance of getting content as well as fill in areas that you know would be useful to have.
  4. Offer rewards. Provide incentives for people to contribute, such as free copies of your products. Microsoft provides incentives through its MVP program, such as paying for travel and attendance at an annual conference. It will end up costing you something, but probably less than a full-time writer would charge.

Tools


There are several tools available to be able to display content from both your own writers and your developer community. Two that I'll mention are Wikis, which are fairly easy to get up and running. However, Wikis tend to look very plain, and getting them to look good can take quite a bit of work and skill. Also, Wikis have the disadvantage of not having sophisticated search capabilities.


MediaWiki


A common tool used for API documentation is MediaWiki. Content is entered into MediaWiki using a simple mark-up language. Although WYSIWYG editors exist, my experience is that for API documentation, using the mark-up language works well. After all, your contributors will be highly technically skilled.
MediaWiki is free, but you will need to host it yourself, and it will require a MySQL database, which is open source. It has a very basic look, but if you are skilled with CSS (Cascading Style Sheets), you can tailor it to match your brand.


PBWorks


If you are looking for a hosted solution, you might consider PBWorks. PBWorks provides a hosted Wiki with a good deal of control over access. Content is created and edited using a WYSIWYG editor that is provided through a browser. You have the ability to create templates, which would be very useful in keeping your formatting consistent.
PBWorks charges an annual subscription for its public edition that allows for an unlimited number of content contributors. In general, it is quite affordable for small businesses.


MindTouch


MindTouch is a commercial software package for collaborative content authoring and Web publishing. If you want to have your documentation visible to the general public, then you need to buy and host the software. It's a very sophisticated package which includes a scripting language that can access content from other systems and create a customized presentation of the content. It can be set up to contain core content that is generated by your company as well as community content that augments the core content. It's priced for enterprise-level businesses and provides a great deal of functionality.

Conclusions


You can't completely eliminate your need for professional programmer/writers by crowd-sourcing API documentation. But a hybrid combination of programmer/writers and community content could make your documentation even more relevant and useful. Programmer/writers will need to write content that does not appeal to the community, as well as polish and verify the accuracy of community content. Tools are available to create community content, from free and simple platforms such as MediaWiki, to commercial tools such as PBWorks and MindTouch.


Comments

1 Comments.
Share a thought or comment...

Anonymous
Comment 1 of 1

Great article, Peter! Another intriguing tool is Pydocweb, which supports wiki-based editing of API documentation comments that are embedded in source files. The updated comments (once they go through an approval process) go back into the source files in source control. This system is designed for Python source files, but the same idea could be applied to any programming language (just a "small matter of programming"). This tool has been used very successfully to improve the API documentation for the NumPy library.

---
Janet Swisher
Posted 49 months ago
 
Write a Comment...
Full Editor
Sign in...

If you are a member, Sign In. Or, you can Create a Free account now.


Anonymous Post:

Enter your name and security key.

Your Name:
Today's security key = P257A
Enter key:
Article Contributed By Peter Gruenbaum:

Peter founded SDK Bridge to bring together his love of technology and writing. He has worked as a programmer writer to describe technologies as diverse as the Tablet PC, mobile phones, and Live Framework. As a software developer, he has written software using Tablet PCs, Augmented Reality, 3D visualization, and computer-aided design. At Red Llama, he created a program to teach creative technology classes to low-income youth to inspire them to consider technology careers, obtaining grant money from the Gates Foundation, Microsoft, and others. This program has now become the "Software Development for Kids" project at SDK Bridge. Peter received his BA in Physics from the University of Chicago and his PhD in Applied Physics from Stanford University .


 KB Article #102203 Counter
5457
Since 12/20/2010
-
  Load Time=less than 1 second.
 
Print This



KB Post Options:
You do NOT have KB edit
rights to this post.
-
 
Have a question? Need our services? Contact us now.
--Mike Prestwood

Call: 916-726-5675

email: info@prestwood.com


625 People Online Now!!  
Sign In to see who's online now!  Not a member? Join now. It's free!
Show more stats...
Follow PrestwoodBoards on: 


©1995-2014 PrestwoodBoards  [Security & Privacy]
Professional IT Services: Coding | Websites | Computer Tech