Documentation Standards Old

From Open Source Ecology
Jump to: navigation, search


June 2011 marks a point of shifting the focus to professional documentation standard development at Factor e Farm. We are at the stage that such documentation is not only indispensable for production runs at Factor e Farm, but also for replication in other places worldwide. Check our Fabrication Procedure Standards.

A proposal for a GVCS documentation template is given in Mark J Norton/GVCS Template.

Video Documentation Toolchain

  • Cinelerra as a free open-source cross-platform video editing software

Cinelerra Home Page

  • Audacity as a free open-source cross-platform audio editing software

Audacity Home Page

Documentation Standards

We propose the following procedure for developing documentation based on prototyping work at Factor e Farm.

  1. Upload all media to GitHub repository [1]
  2. Publish detailed fabrication procedure on wiki
  3. Fill in with pictures, jpg of CAD files, and links to actual CAD and CAM files in file repository
  4. Develop an instructional video based on wiki fabrication procedure and any additional material from media FTP repository

GVCS Documentation

Each GVCS tool should have OSE wiki pages with sections that deal with the following:


  • Overview
  • Detailed Description and Features
  • Components
  • Product Ecology
    • Uses
    • Creates
  • Solution Statement
  • Specifications
  • Status
  • See Also

Research & Development

  • Overview
  • Research
    • Goals
    • General Design Goals
    • Features
  • Advantages
  • Design
  • Funding
  • Peer Reviews
  • Experiments and Prototypes
  • Experimental Results
  • Prototype Notes, Observation, Etc.
  • Failure Mode Analysis
  • Testing Results
  • Recommendations for Improvement
  • See Also

Bill of Materials

  • Google Docs

Manufacturing Instructions

  • Prepare
    • Safety
    • Workspace
    • Tools
    • Raw Materials
  • Component Fabrication
    • Cut
    • Drill
    • Misc
  • Assembly
  • Programming (if any)
  • Finish
    • Paint
    • Test

User's Manual

  • Overview
  • Safety Procedures and Considerations
  • Operation Procedure
  • Maintenance
  • Breakdowns and Repair
  • Assembly
  • Disassembly

Documentation at Other Locations

As other locations come online, similar procedures should be implemented to facilitate contributions to the overall project.

Design Designations and Document Identifiers

As GVCS and other OSE tools mature, it will become difficult to keep documentation organized. For identification purposes, a standard design iteration naming convention is proposed. Each GVCS tool should be assigned a standard set of initials, LT for LifeTrac as an example. Product iterations (models) can be either identified as P1, P2, etc. or given a descriptive name such as Rear Mounted Engine. Thus, the current LifeTrac-2 would be referred to as a LT-P2 for documentation identification purposes. It is quite possible that several design iterations are needed within a product model, thus the third design of the LifeTrac-2 would be referred to as LT-P2-D3. The first design of the rear mounted engine could be known as LT-REM-D1.

The main point of this identifications scheme is to create a name space that allows all documentation to be grouped together for a single design iteration. Thus, the video that shows how to fabricate the back right wheel mount panel can be called "LT-REM-D1-Back-Rear-Wheel-Mount-Panel.wmv" and the related 3D CAD render could be called "LT-REM-D1-Back-Rear-Wheel-Mount-Panel=CAD-v2.png". Note that this is version 3 of the render.

See Also

Video Documentation

See Documentation/Video

Video Documentation Best Practices