Building a Docs Community

DZone 's Guide to

Building a Docs Community

· Java Zone ·
Free Resource

Open source projects rely heavily on developer communities for valuable input, and NetBeans is certainly no exception. As part of the NetBeans Community Docs program, members from around the world contribute screencasts, tutorials, tips & tricks, translations, and other important documentation to the community. It's a perfect example of how a community can help itself.

As a technical writer for the NetBeans documentation team, my daily tasks include writing and editing documentation designed to teach users how to use the NetBeans IDE. Like any writing team, the NetBeans team does its best to publish as many high-quality docs as possible for each release, but unfortunately time and personnel constraints can have an negative effect on the number of docs that actually make it out the door. Of course, hiring more writers would alleviate the problem, but by doing so a very valuable resource would remained untapped: the NetBeans Community.

NetBeans Community members have always played an important role in the development of the IDE. In 2000, when NetBeans made the decision to embrace open source development, the role of the community contributor became even more important. However, as far as community participation is concerned, documentation has taken a back seat to other areas of development. This is unfortunate because there is a tremendous amount knowledge in the community, and by channeling this knowledge to the production of documentation, the NetBeans user experience can only improve. Thus, in February 2007 the NetBeans Community Docs program was born.

The obvious goal of the Community Docs program is to increase the amount of NetBeans documentation. By encouraging community members to create and submit tutorials, screencasts, FAQs, and other documentation, more IDE tasks and user scenarios can be covered. And the more ways a community member can give back to the community, the stronger the community becomes, and this is how open source projects were designed to work.

Starting Up

Building a community docs program from scratch might sound harder than it really is. True, a lot of time was spent considering strategies, a lot of blogs were scanned looking for material, and a lot of emails were written to community members asking them to participate. However, what made this job a whole easier was the overwhelmingly positive reaction of community members. I would even go so far as to say that some members of the NetBeans community had been waiting a long time for such an opportunity to contribute.

The NetBeans Community has always been an active community. Try entering NetBeans into any search engine, and the ensuing search results will contain blog after blog of information on NetBeans. And because of the sheer number of blog entries out there that are dedicated to performing certain tasks using NetBeans, blogs were the most logical place to start looking for content. After several potential blog entries were identified, comments were left on the blog, asking the author if he/she would like to participate in the program. Needless to say, many did participate, and soon solicited contributions began to show up in the Contributions table on the NetBeans Community Docs wiki at http://wiki.netbeans.org/CommunityDocs.

While blogs were being located and authors contacted, NetBeans writers and evangelists were busy getting the word out that the Community Docs program had been created. A mailing list was designated for communication among contributors: dev@usersguide.netbeans.org, and soon thereafter unsolicited contributions began appearing on the Community Docs wiki.

At the time this article was written, 107 contributions had been made to the NetBeans Community Docs program.

Figure 1. Documentation Contributions by Month: March 2007 – June 2008

Every day, community contributors communicate with each other on the dev@usersguide.netbeans.com mailing list and in groups at www.facebook.com and www.MySpace.com.

Today, the majority of contributions to the NetBeans Community Docs program are unsolicited. However, blogs are still monitored on a regular basis, and every effort is made to encourage NB community members to contribute more than once. A few community members have even contributed several times.

Community Docs Contribution Coordinator

As the NetBeans Community Docs program began to grow, it became clear that the amount of work involved would require that a second person be assigned to the program. Since the program was created for the community, I felt that this person should be a member of the community. In August of 2007, the position of Contribution Coordinator was created. The primary role of the Contribution Coordinator is complex and involves helping to identify potential documentation, assisting users in making the transition from HTML to wiki, answering questions on style and content, and blogging about the program. Amit Kumar Saha, a technical writer and student from India was chosen to fill this position. Not only has Amit's work in the program had a significant impact on the overall success of the program, he has also served as the perfect liaison between NetBeans technical writers and community contributors.

Figure 2. Amit Kumar Saha, Original Contribution Coordinator

Since then, however, Varun Nischal has taken on Amit's role.

Figure 3. Varun Nischal, New Contribution Coordinator

  • Docs for Eclipse Users
    One of the most important goals of the the NetBeans Community Docs program is to drive the adoption of NetBeans. To address this goal, Amit Kumar Saha has created a separate wiki for former Eclipse users who have switched or are in the the process of switching to NetBeans. The wiki focuses on migrating existing Eclipse projects to NetBeans and serves as a very useful guide for those interested in switching. Amit has written some of the documentation himself and has also received help from several community members.
  • Code for Freedom
    Another area where Amit Kumar Saha has been a great asset is managing contributions that could qualify for Sun Microsystem's Code for Freedom contest. Although the NetBeans Community Docs program is not connected to the Code for Freedom contest, Amit has been available to answer developers' question about the program and contest and, when necessary, provide details for those participating in both.

Figure 4. James Branam, Community Docs Manager

NetBeans Community Docs Today

The NetBeans Community Docs program has already established itself as a valuable source for NetBeans documentation. NetBeans technical writers and the NB web team are working hard to integrate community-contributed documentation into existing web-based learning trails and technology indexes on netbeans.org. Due to the number of contributions to the program, archiving of older contributions has begun. Archived contributions can be viewed at http://netbeans.org/community/commdocs.html and are also linked from the main Community Docs wiki page. The dev@usersguide.netbeans.org mailing list is becoming very active, and NetBeans Community Docs groups have been created on www.facebook.com and www.myspace.com, Membership in these groups is growing fast.

The Future of the Program

The future of the NetBeans Community Docs program lies in the hands of community members. As the program grows, community members will be asked to take over more parts of the program. The role of the Contribution Coordinator is expected to expand as well, assuming new managerial responsibilities.

The program will also being used to address the need for certain types of documentation. For example, community members are currently being asked to provide documentation featuring MySQL and PostgreSQL databases with NetBeans. In the future, there could be other needs that are required to be met. Whatever need arises, the NetBeans Community will be there, ready to step up.


How to Contribute

Here's how to contribute to the NetBeans Community Docs program:

  1. Go to the NB Community Docs wiki at http://wiki.netbeans.org/CommunityDocs.

  2. Choose a document from the wishlist or create a new topic for your contribution.

  3. Send an email to james.branam@sun.com with the name and subject of your contribution.

  4. Put your contribution in wiki format and link to it from the Contributions table on the main Community Docs wiki. Wiki formatting instructions can be found on the main wiki.

  5. Sign up to the dev@usersguide.netbeans.org mailing list.

It's really that easy. The NetBeans Community is looking forward to seeing your contributions.




James Branam (james.branam@sun.com) is a technical writer for NetBeans web application development and Manager of the NetBeans Community Docs program.


Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}