P:Documentation Standards::Iterative Documentation Flow

Intro

These are documentation processes for people doing the work. Ideally, folks can document with 5 minutes of their energy for 55 minutes of creative work. This makes it so that folks know where things are at in a lightweight way. Then, let documentation improve as more folks replicate the work.

Use this documentation process when you're making machine prototypes so that others can get the support they need to replicate.

Overview: Phases of Documentation

There are 4 phases of documentation: first pass, team-ready, workshop-ready, and public-ready.

1. First Pass

This is just a bare bones description of steps you followed to do the work. Please see below for instructions, a template to use, and a short video explaining hot tips and pointers.

2. Team-ready

This is produced when someone from the OSE team goes over their work with a documenter who fills out details from the First Pass documentation. See below for instructions, a template to use, and a short video explaining hot tips.

3. Workshop-ready

This is produced after a prototype has reached maturity to be shared with the general public. Folks take pictures to assist in a build and include support for understanding design concepts. Use the 6 layer documentation document as a base.

4. Public-ready

This starts as being the same as a workshop-ready manual. It is improved upon by enlisting workshop participants to ask questions that workshop leads log into a forum. Afterwards, OSE project stewards add the information to the manual, include a note about where to find this newly available info in the forum, and then add a specific emoticon that signifies the concern or tension has been integrated.

Over time, the public-ready documentation will steadily improve because there is a process for capturing that tensions that people experience and addressing them.