Introduction
Helping with documentation is one of the easiest ways to get involved in the fantastic Ubuntu community if you do not come from a technical computing background. Good documentation is critical for the Ubuntu project because it helps our users overcome any difficulties that they may encounter, whether they are trying Ubuntu for the first time or have been using Ubuntu for some time.
There are two primary forms of documentation in the Ubuntu community. They are:
System Documentation - the documentation that comes with every Ubuntu, Kubuntu, Xubuntu and Edubuntu system. It includes the Ubuntu Server Guide.
Wiki Documentation - a community edited resource that anyone can edit.
Both types of documentation are well suited to a Jam. For an initial contributor to Ubuntu documentation, the wiki documentation is the best place to start. Anyone can edit the wiki documentation, and the markup used to create the documentation is straightforward and easy to learn. The system documentation is not free for anyone to edit because the material is present in the help center of every Ubuntu desktop and a stricter system of quality control is adopted there. However, it's easy to learn how to contribute to the system documentation as well.
Requirements
Tutor(s) - Someone with experience in technical documentation who can handle questions about writing style or the tools and review changes. (The tutor needs to have experience with Ubuntu documentation and the Ubuntu documentation process.)
Decided Day - A day with some spare time. As an example, the Michigan LoCo Jam went from noon until 8pm on a Saturday. Progress will be slower than you might expect, so provide plenty of time.
Venue - A meeting location with network connectivity, power for everyone, and some room to get comfy for a little bit.
Documentation Playbook (optional) - a generic sheet that you can print out and hand out to attendees, so that they can follow along with the workflow for the system documentation - see System Documentation Playbook.
Virtual Jams - Jams over IRC or another online service. A physical location is not necessarily required to run a jam, although if you can get together in the same place, we do encourage that. Most documentation work in the Ubuntu community is done by volunteers based all around the world, so virtual collaboration is common. A virtual jam might be preferred if you don't have a tutor available for a physical jam and would like to ask one of the existing DocumentationTeam members to act as the tutor. If you want to run a virtual jam, we suggest that you:
Subscribe to the mailing list and suggest a time and date for the Jam.
- Discuss the planning for the Jam on the mailing list
- Get together for the Jam in the #ubuntu-doc channel on the freenode irc network
Preparation
Preparation is not essential, but it will save time and allow the Jam participants to spend a lot more time working on improving the documentation rather than learning the ropes.
Those attending should therefore be asked to read the DocumentationTeam pages on the system documentation and wiki documentation. The key pages for the system documentation start at DocumentationTeam/SystemDocumentation and the key pages for the wiki documentation start at DocumentationTeam/Wiki. For those wishing to work on the wiki, we strongly encourage you to read the Wiki Guide.
Holding the Session
Introduction Session
- Introduce the system documentation and wiki documentation, and assess the level of preparation that has been done.
- If some review of the tools is necessary, introduce the tools used.
- Discuss whether the jam will focus on wiki documentation, system documentation, or a bit of both.
- Plan some tasks to be taken on by different contributors (see below).
Tasks
DocumentationTeam tasks are listed on the following pages:
Read those pages for examples of things that you can do at a Jam. Feel free to choose from these. Depending on how confident you are feeling and how familiar you are with the tools, you might like to:
- Review wiki pages or system documentation to identify errors and report them as bugs
- Identify existing bugs and fix them
Cleanup wiki pages marked with tags as needing work
- Write a new document on a subject that doesn't yet exist (don't forget to plan the structure first)
You might want to pick a particular theme for a Jam. For example, the jam participants could work as a team to plan a new document and divide individual sections between the different participants. Or you could focus on a particular area of the wiki that needs work. If you are planning a themed jam, discuss it in advance on the documentation team mailing list so that your work does not duplicate work that might already be in progress by others.
Workflow
- As people work on documents or wiki pages, keep track of the number of documents worked on. This can be done with tomboy notes, a marker on a whiteboard, or some other means. It is important that you have some number so that you can measure improvement and progress as you have more Jams.
- Try to group people who have similar interests in groups, so they can try to work on documents together and answer questions in a group.
Tools & Helpful Information
All the information necessary should be found on the DocumentationTeam page and the pages linked from there. If you have any questions, feel free to contact the team to ask.
Get help on #ubuntu-doc.