Product SiteDocumentation Site

8.5. Using Documentation as a Way to Get Involved

Documentation has a reputation as being an easy way to begin contributing to a project. This is more true where the new contributor is already experienced or an expert in the material. It is much less likely to be true where the project has not considered how to enable good and easy documentation, or the technical content is very high.
When developers resist documenting, it is usually around several themes:
  1. The tools are painful to use.
  2. Writing is not a principal skill.
  3. It takes too much time, usually because of 1 and 2.
The techniques for creating a successful documentation project that attracts contributions from actual project developers are mirrored answers to these problems:
  1. Focus on making the tools easy to use and aligned with the developer team's preferred methods or built in to the workflow.
  2. Turn writing in to a brain dump , that is, an outpouring of information without concern to writing standards (grammar, spelling, or structure).
  3. Enable non-developers to provide significant contributions by saving the developers from the actual work of writing, which is structuring and editing.
Dumping down words in to a text editor is not very hard; many developers write copiously in email, for example. The documentor's challenge is finding this content wherever it is (mailing lists, IRC discussions, random wiki pages) and editing it in to something comprehensive that reveals content holes for filling. The documentation project's success hinges on the ability to restructure rambling content and make all of that accessible to new writing contributors, so they can begin meaningful work from the very start.
A metric of this success is when any random experienced contributor is asked a question by a new contributor, and in answering, insists that the answer be documented, for example, on the project wiki using existing templates, etc. In this way new contributors are turned in to documentors who share the work burden from the existing contributors.

8.5.1. Exercise - Getting Involved

  1. Take your technical document content plan and prepare it to show to developers and writers involved in the FOSS project.
    • For example, use a personal user namespace on the FOSS project's wiki "User:Username/New_page".
    • Alternately, prepare it for inclusion in email.
  2. Join the documentation mailing list; if there is no specific documentation list, join the main developer list.
  3. Send an email with your content plan and any work done so far, request comments on content and where you are getting information from.
  4. Proceed with writing a first draft of the content based on your plan and comments received.
  5. If you get stuck, return to the mailing list or ask on IRC. Your earlier introduction and content plan makes this part easier.
  6. Return with your next draft to the mailing list, asking for a review and comments. Provide enough time, several days to a week, and be sure to engage in discussion about the content in a timely way (at least once per day.) The goal of this step is to improve the content in accuracy