Documentation Standards: Difference between revisions

From Open Source Ecology
Jump to navigation Jump to search
No edit summary
Line 1: Line 1:
see [[Documentation Standards Old]]
=Introduction=
=Introduction=
As the project moves towards viral replication, it is important to create effective documentation standards.


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]].
=Design Rationale=
 
The scope of effective documentation standards for OSE is:
A proposal for a GVCS documentation template is given in [[Mark J Norton/GVCS Template]].
*Understanding the standards makes it possible to navigate both graphically and via the address bar on the OSE wiki - to access any piece of documentation for any machine.
 
*Machine naming is standard. Currently, the names used on the main site at opensourceecology.org are used.
=Video Documentation Toolchain=
 
*'''Cinelerra''' as a free open-source cross-platform video editing software
 
[http://cinelerra.org/ Cinelerra Home Page]
 
*'''Audacity''' as a free open-source cross-platform audio editing software
 
[http://audacity.sourceforge.net/ Audacity Home Page]
 
=Documentation Standards=
 
We propose the following procedure for developing documentation based on prototyping work at Factor e Farm.
 
#Upload all media to GitHub repository [https://github.com/organizations/OSE]
#Publish detailed fabrication procedure on wiki
#Fill in with pictures, jpg of CAD files, and links to actual CAD and CAM files in file repository
#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:
 
'''Home'''
* 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==
*[[Fabrication Procedure Standards]]
*[[Development]]
 
=Video Documentation=
See [[Documentation/Video]]
 
[[Video Documentation Best Practices]]
 
[[Category:Documentation]]

Revision as of 23:31, 1 December 2012

see Documentation Standards Old

Introduction

As the project moves towards viral replication, it is important to create effective documentation standards.

Design Rationale

The scope of effective documentation standards for OSE is:

  • Understanding the standards makes it possible to navigate both graphically and via the address bar on the OSE wiki - to access any piece of documentation for any machine.
  • Machine naming is standard. Currently, the names used on the main site at opensourceecology.org are used.
Retrieved from "https://wiki.opensourceecology.org/index.php?title=Documentation_Standards&oldid=82256"