8.7. Documenting Technical and Community Proceedings

This section is focused on reasons and methods for documenting community proceedings, such as developer conferences or technical steering group meetings.

These are the skills used by standards organizations around the world, and are very similar when used as part of the open source development model. Where open source projects might differ on the specifics of how something is done (the tools), the reasons why and the type of information captured and revealed are common across free communities.

The principles are:

Document as much as possible of what occurs in any community meetings and interactions.
Use as much automagic as possible, such as IRC logging bots.
Choose open, common, collaborative tools; not just "a wiki" but "MediaWiki, the popular and well-understood wiki system".
Use these tools in real time during the proceedings.
- For example, the Gobby text editor is an open source tool for simultaneous real-time editing/writing of a document between two or more people on separate systems across a network.

8.7.1. Exercise - Document Proceedings

This exercise lasts throughout the class session. It is best done early in the year to gain full benefit of the documentation that results.

Create a page on the class wiki that lists each class session by date.
For each date, assign one or more persons to be the documenter for that day.
- Depending on class size and session length, you may want to have several students take turns during a single class session.
The documenter has the job of transcribing the proceedings directly in to a wiki page named for the class session, e.g. Open Source 101 - YYYY-MM-DD session notes.
- Make sure to use proper wiki syntax, categorization, etc.
- Cross-link to other information, such as the instructor's published lecture notes, rather than rewriting everything. Use URLs to cite and reference.
- Take notes of what other students ask and discuss.
- Focus on getting down the facts, save editing and spell checking for later.
- It may be hard to participate in the discussion while being a documenter.
- Take turns if it helps, especially at the beginning.
- Take pictures of information in the room, such as whiteboard/blackboard work.
As that page is created, it becomes the canonical node for that particular class session. For example, additional content or homework for that session could be linked from that page, etc.

A bonus exercise is this:

Use the classroom IRC to log a discussion during the class. The documenter writes notes directly in to IRC. Other class members can annotate in this back channel as they proceed.
Convert the log to HTML or otherwise make it available for linking from the wiki page.
On the wiki page, include a summary of the session and any other relevant meta-data, such as links to lecture notes, source code, test instances, and so forth.