8.2. Common tools and Processes for Open Source Documentation

Documentation requires tools that are very similar to those used in coding.

Editor to write content in.
Means to collaborate with other writers and technical contributors.
Version control, as explained in Getting the Code(XREF).
Means to markup, build, and publish draft and finished documents.
Processes to use these tools as part of a collaboration.

Typical thinking about documentation focuses on certain parts of the tools, such as the editor (Emacs, Vi, etc.) or the markup-build-publish tools (XHTML, TeX, Docbook, etc.). A content management system (CMS) such as Drupal or Wordpress has all of the requirements built in one tool. The structure of the tooling enforces a loose, strict, or customizable process.

For example, Wordpress is a CMS that is focused on one or a group of writers producing content that appears in news fashion on a website. The tools loosely enforce a process of editing drafts, previewing, categorizing and tagging, organizing by date etc., and scheduling or pushing to publish.

For the exercises in this chapter you are going to use a classroom wiki, which simulates the wiki used for an open source project by developers and other content contributors, and also the actual wiki of an open source project you choose to document. MediaWiki is a commonly used FOSS wiki tool and is used in these exercises to assure clarity and consistency. For other wiki tools, you may need to make changes for the syntax or tool flow.

8.2.1. Exercise - Document Your Team

In this exercise you learn how to use a wiki, including page creation and editing.

Requirements:

Class wiki web service.
Wiki account or ability to make one.
- Ideally an open source project makes it clear how to get edit access to the documentation tools, which may include a wiki. For this class, the instructor may have created your basic account on a classroom wiki instance.
Internet Relay Chat (IRC) room with class attending.
- IRC is a main tool in open source development; chat logs form the basis for documentation and other knowledge. You need to get comfortable working in an IRC environment.
- Read additional online content about chat skills and etiquette in advance of class.
One hour.

Work in collaboration with other members of the class.
- IRC is preferable to get the full open source experience. If in the same classroom, work without speaking aloud, only via IRC and the wiki.
Your goal is to create a wiki page about yourself. It should include:
- A brief biography.
- Preferred contact methods and information.
- A list of projects you are working on for this class.
- A list of class sections completed with links to source code, logs, etc.
However, you may not write any of the content yourself.
You must work with one or more classmates to get your page created.