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

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