The OSHW Documentation Handbook
- Overview
- Dashboards
- Documentation Taxonomy (semantic tagging)
- Languages
- File Format Standards
- Towards Modular Documentation
- Designs & Code
- How to communicate effective Conceptual design
- Standards for CAD drawings
- Build Instructions
- Bill of Materials & Parts Lists
- Simple and Language-agnostic Build Instructions
- How to Describe Tooling
- Critical Elements of Fabrication Procedures
- How to Communicate Quality Control Procedures
- Documentation Components
- Mechanics & Assemblies
- Electronics
- Hydraulics & Pneumatics
- Optics
- Materials
- Software
- Delivery Platforms
- Software
- Hardware
- Collaboration Tools
- Suggested Information Architecture -
- Hardware Info
- Build Overview
- Building Modules
- User Manual
- Open Enterprise Model
Overview
The Open Source Documentation Handbook consists in a set of standards and best practices for the documentation of open source hardware with the specific goal of enabling practical replication, modification, customization, and repair of open source devices. The handbook seeks to address issues such as identification of documentation components; accessibility of file formats, software and hardware; language-agnostic build instructions; and a modular approach to enable the remix and mashup of documentation to create hybrid devices by combining parts of different documentation sets (eg. the code from one project with the electronics or mechanical components from another).
The desired outcome of this collaborative project is to arrive at a set of principles — and practical suggestions for the effective implementation of those principles — to be adopted by open source developers.
Dashboards
At a glance information. Includes:
(add specifications - see tv-b-gone)
BOM, Parts Lists & Materials
- Parts lists should include: item name, item description, quantity, dimensions, price, source, notes, part number, link to datasheet, image + manufacturers/distributors and cost info whenever possible.
- Parts lists should be distributed as attached text files if the list is more than a dozen parts.
- From Nathan: “A spreadsheet of parts used in the device. This may include or link to other OSHW projects (Russian dolls). Example formats: CSV, XLS, Google doc. If your CAD package has integrated or add-on BoM management tools, those are also a good option. Examples include the built-in tools in SolidWorks and bom-ex for Eagle. Sometimes this is simply a human-readable text file with one line per tool, material, reagent, etc. Including part numbers, suppliers, and vendor information is encouraged!” (http://www.oshwa.org/sharing-best-practices/)
- Provide information on alternative materials whenever possible
File Formats
- Provide all files in more than one format (eg. DXF but also PDF, google sketchup but also STL)
- Provide vector or hi-res raster images to allow zooming in on details
- For electronics:
- Schematics in eagle or other source format, preferably open source such as fritzing, but also PDF. If possible, provide breadboard view from Fritzing.
- PCB files in gerber format.
Hardware Components
Digital Fabrication
- Textual description w/ link to translate
- Fabrication diagrams: 2D and 3D CAD drawings: http://sketchfab.com/faq#embed
- CAD drawings, preferably in one or more standard formats - PDF + DXF for subtractive manufacturing, STL + Google SketchUp + SCAD for additive manufacturing.
- Preview of 2D (PDF, BMP, PNG, GIF, JPG) and 3D CAD files (STL, Google Sketchup, etc.)
- Fabrication Drawings
- IKEA-style fabrication diagram
- Assembly instructions: Exploded view drawing, Step by step instructions IKEA-style (w/ drawings and//or photos), Instructional videos, HowDos
- 3D model of assembly
- Fabrication procedure
- Machine settings for fabrication and for CNC (eg. power/speed setting for laser cutter)
- CAM device-specific file
Electronics
- Textual description of component w/ link to translate
- Schematics (symbolic representation of the circuit, showing how to connect the components), preferably in hi-res PDF, BMP, PNG, GIF, JPG. Use Fritzing? Other formats: Eagle, Altium, KiCad, gEDA, BRL-CAD
- PCB layout (concrete representation of the circuit, used to fabricate PCBs), in vector artwork format preferably as Gerber/Excellon and PDF.
Software
- Source Code (annotated)
- Firmware
- Example formats: text file, repository, zip
- Instructions for installing, compiling, etc.
- Any libraries or links to libraries that are needed
- An honest assessment of the state of the code: Beta, “a barely working hack”, etc.
- Adequate documentation of things that are done verses things to do, as well as any authors/sources referenced (this is not specific to code).
- Use version control.
Additional unconfirmed notes
Potential data format: XML
A potential solution to hold the taxonomy is to use XML format http://en.wikipedia.org/wiki/XML.
Extensible Markup Language (XML) is a markup language that defines a set of rules for encoding documents in a format that is both human-readable andmachine-readable. It is defined in the XML 1.0 Specification[3] produced by the W3C, and several other related specifications,[4] all gratis open standards.[5]
The design goals of XML emphasize simplicity, generality, and usability over the Internet.[6] It is a textual data format with strong support via Unicode for the languages of the world. Although the design of XML focuses on documents, it is widely used for the representation of arbitrary data structures, for example in web services.
from Wikipedia
Advantages:
Purpose | XML was actually created to model documentation in a simple, human readable format | |
Portability | You don’t need any stack or program to read it, it’s even readable in printed format. ANy VM is needed | |
Expandability | Anyone can expand an XML without breaking the validity (XSD validation) | |
Availability of tools | XML is among the most common format all over the web. A bunch of editors and readers are available. Could be read also via any Browser | |
It’s possible to embed files | Files can be embeddeed with any encoding | See: http://stackoverflow.com/questions/19893/how-do-you-embed-binary-data-in-xml |
The overall idea is to use an XML file to transport data easily in a human readable + machine readable format.
Definitions: XSD
The best tool to create the taxonomy the documentation shall be validated against is actually XSD (or XML Schema http://en.wikipedia.org/wiki/XML_Schema_(W3C))
XML schemas have been used to describe several complex artifacts ranging from as business documents to music playlists
http://en.wikipedia.org/wiki/List_of_XML_schemas
Without the validation coming from an XML Schema (XSD file) a XML file is a relatively free set of elements and attributes. XSD file define which elements and attributes are permitted and in which order.
