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 brief overview of these 4 phases followed by the next section with actual instructions to complete each phase.

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 when during workshops, instructors log and answer participant questions until the documentation is comprehensive and matches the documentation standards.

First Pass Documentation: How to do it

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 record enough info to improve the documentation later on. Aim to get a skeleton. 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