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.

Team-ready documentation: How to do it

Team-ready documentation occurs in preparation for and during the first replication of a prototype.

See here for Template: Team-ready Documentation

Orientation: Key things to keep in mind.

• When creating a build phase, try to minimize the number of quality control approvals. This creates unnecessary work. If 2 items both needs checking, but can be independently built, then it's better to check them both at the same time and put them in the same build phase, rather than create 2 build phases.
• Before the replication, write for speed so that it makes sense to you.
• During the replication, write for your teammate so that they understand what you've written.

Workshop-ready documentation: how to do it

Before you give your first workshop, take the team-ready documentation and have it fit the Template: 6 layer documentation.

See the 3D Printer Manual for an example.

Public-ready Documentation: How to do it

Add themes to your build phases for novice hardware builders and create another Q&A doc with sections with each build phase.

See 3D Printer Quality Control Lists for an example.

During a public workshop, insist that all participants only ask questions to instructors. Train participants to reference the Q&A before asking a question. Instructors document all questions and answers.

Links

This page is based on Documentation Standards