P:Documentation Standards::Iterative Documentation Flow

Intro

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

This process uses iteration and process to steadily improve documentation over time based on real people's needs.

This process takes place in entirety before reaching the quality as stated in Documentation Standards.

Ideally, solo folks can document with 5 minutes of their energy for 55 minutes of creative work, and only when there's multiple people replicating existing work does documentation improve and receive more energy.

Overview: Phases of Documentation

There are 4 phases of documentation: first pass, team-ready, workshop-ready, and public-ready. See below for actual instructions to complete each phase of the documentation, including templates and videos.

1. First Pass

This is just a bare bones description of steps you followed to do the work.

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.

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.

Instruction: How to do First Pass documentation

First pass documentation significantly increases the ease of documenting your work in the future.

See here for Template: First Pass Documentation.

Orientation: Key things to keep in mind.

As a project steward, the purpose of first pass documentation is to help guide another team member in documenting the work that you're doing, when you assist them in also doing the work at a later time. Because you will be there to improve the documentation later, the point here is just to get a skeleton down that can help orient future documenters. Therefore:

• Don't spend a lot of time documenting the work, aim for under 5-7 minutes for every 55 minutes of work.
• Aim to create a "captain's log" -- it's good as long as you can understand it when you read it, even if others can't.
• Focus on doing the work and not documenting the work
• If you can, include individual steps that you took, even if it's just a 5-7 word description.
• Don't explain why - this is something the person who doesn't know everything you do should write instead, because they have a beginner's mindset. This will be done in team-ready documentation.

Template: First Pass Documentation

Make a copy of this template, rename it, and write your first pass documentation there: Template: First Pass Documentation

Here's an example.

Video Instruction

Here's a short video of Alex filling out the first pass documentation.

Links

This page is based on Documentation Standards