Documentation Standards

Introduction

As OSE moves towards viral replicability, it is important to create effective documentation standards. This applies to the work of OSE and also towards creating a broader platform for open source product development. To this end, we are studying existing open source industry standards - to pick out existing best practice and to integrate these into a larger platform. The strategy is to remix as many existing tools as possible - while inspiring the related players to contribute to a greater platform.

The scope of Open Source Ecology involves machine and organization level items leading to the Open Source Economy. In Phase I (January, 2013), we are defining the standards for the 50 GVCS machines, which is intended to be a beta test for a larger platform that scales to any number of items - encyclopedic scope. Organizational aspects for creating the open source economy will be developed in Phase II (February, 2013).

The current priority is to standardize a format for documentation on the OSE Wiki.

Working Document

edit

Open Hardware Documentation Outline

edit

Documentation Platform Principles or Specification

• Language agnostic platform
• Readily publishable in part or in full in hard copy or digital copy
• Promotes the open source economy and distributive enterprise
• Clear contributor agreements and user license
• Work Product is a Protocol, not Platform. Distinction is Protocol can be implemented on any platform.
• Platform, hardware, and software agnostic. Uses open software formats; accepts proprietary formats so they can be translated.
• Contains a commit and quality assurance mechanism
• Upvotability and quality upgrade mechanism, versioning
• Modular design of documentation, clear modularity standards for how documentation components fit together, and easy interfaceability between modules
• Resource Description Format markup for semantic web compatibility. Tagging and markup for mashup and remix purposes. API for interoperability with other platforms.
• Breadcrumbs - location guide or secondary navigation scheme
• Well-defined tagging standards.
• Entry-level access for contributors (not a geek protocol)
• Incentivizes participation with other open source and closed source platforms.
• Glossary is incuded, platform is self-explanatory.
• Meritocratic governance
• Provides an assessment mechanism for 'state of open-sourceness' of projects
• Facilitates quantitative assessment or statistics about open hardware projects in general
• Encourages DIY projects to join open source economic framework, and invites uninitiated DIY projects to add value to their work and to the world by making their work more visible
• Fosters Technical Literacy
• Ready verifiability

Work Product

edit

Value Proposition

The value that we propose to add to defining documentation standards is:

• Basing platform on existing tools - building on open source industry standards and using non-open source tools only if necessary until they can be substituted.
• Developing interfaces between existing tools, not developing new tools (remixing and mashup)
• Documenting that interface with Brick Press as our test case
• Defining a protocol for documentation based on existing tools
• Getting feedback from the greater community, and defining a role for a Documentation Director for Scalable Open Source Product Distributive Enterprise Development Projects.

Design Rationale

The scope of effective documentation standards for OSE includes Machine, Organizational, and Wiki level areas of documentation.

Organizatinal Level

• The organizational level involves documentation related to running a GVCS-based development, production, or other applied project.
• Enterprise development documentation.

Machine Level

• 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.
• Each machine has a Core and Supporting documentation set. The Core set includes those pieces of documentation that are indispensible for the safe and effective building and usage of GVCS tools by inexperienced builders/users. Supporting documentation is that which allows for the modification, remixing of modules, and other hacks on the machines. It also includes that information which makes replication easier, but which is not critical to such replication - by a novice builder.
• Each Machine has a finite, well-defined set of Core Documentation and Supporting Documentation.
• Supporting Documentation consists of Wiki-level (such as Links section or Index) and Machine-level items (such as CAE analysis - noncritical but desirable for replication)
• Standards are consistent with Open Source Hardware Association Open Source Hardware Definition.

Wiki Level

• Each machine has a particular set of wiki-level Supporting Documenation items - such as Links (example below). Standards are defined for each of these Supporting Documentation item

Specific Wiki Page Structure

Current work on Frame_DXF_Files indicates that a rigorous structure of documentation needs to occur for completeness. This structure should be represented as an infographic with design rationale (for documentation steps) captured.

Links

Past Work of OSE

• See video in Shuttleworth Fellowship 2013 Submission - overview of prototyping and documentation goals. Read entire application.
• OSE Specifications - value proposition of Open Source Ecology
• Open Source Hardware Modularity Pattern Language - technology primitives, GVCS-centric
• Open Source Technology Pattern Language - technology primitives, GVCS-centric
• Kickstarter shows a good overview of what proper documentation includes - see minute 1:22 at Kickstarter campaign of 2011.
• Communications Strategy
• GVCS Interface Design Standards
• See also Documentation_Standards_Development
• See also Process Documentation Standards and Process Documentation Standards Abstract
• Documentation Standards - beginning on documentation
• Flashy XM is an experimental platform in progress, but it does not make the critical distinction between Documentation and Development.
• GVCS tool template from 2011 - Template:ToolTemplate - an actual template in Media Wiki
• More detailed template for each page - see Template:CEB Press Manufacturing Instructions Navbox and this example of Brick Press Drawer.
• See Documentation Standards Old
• GVCS Interface Design Standards
• OSE Machine Development Process
• OSE Machine Documentation Process
• Fabrication Diagram
• Development Work Template

Related Work

• Open Hardware Repository
• http://www.ohanda.org/
• http://oshwa.org
• Make Projects - http://makeprojects.com/
• OKFN Open Design Definition
• Qwiki - see example of induction furnace.
• IKEA Furniture Documentation Standards
• Check out Army Manuals standards for documentation. What other best practice manuals are there? Check the Noun Project.
• Open H20 standards development - [1]
• Documentation Standards Development
• OS Hardware for Humanitarian Aid - [2]
• LadyAda's Layers of Licensing
• OSHWA's FAQ - What files do I need to share?
• OSHWA's Sharing Best Practices
• Open Source Hardware group on Google
• Vinay Gupta
• Extreme Modularity Resource Map
• WikiHouse

Meta

• Resource Description Framework (RDF) - [3]. From Wikipedia article - Creative Commons - Uses RDF to embed license information in web pages and mp3 files.
• Semantic Media Wiki extension - SMW adds semantic annotations that allow a wiki to function as a collaborative database - [4]
• Semantic Web Challenge
• Project Halo - The appendix to Paul Allen's new book, Idea Man, describes several challenges in artificial intelligence for which Project Halo is actively seeking solutions. We are actively seeking people and organizations with serious and well-grounded technical ideas that can result in significant progress against these challenges. Please use the Idea Submission Form to contact us with a sketch of your idea, along with any supporting evidence that it will be successful. Please do not send confidential or proprietary information to Project Halo using this site or through any other means. - see http://www.projecthalo.com/