|Taxonomy Item||Guidelines||Ex.||Rationale for Guideline||Format||Rec. File Type||Suggested Tools||Priority||Development Tasks||Who||Development Platform Item||Guidelines and Rationale||Suggested Tool|
|1||Project URL||A canonical Universal Resource Locator for this project. This should ideally not change, and so other projects can specify this URL when referring to this unique project, for example, as part of the dependency or geneology. This URL (unlike name) unique identifies this project. It does not identify a particular version, and instead should indicate the latest stable version. If the project moves, use a HTTP 302 redirect to indicate this.||While name could be used to provide unique identification for a project, the web does this better, and is already setup to uniquely define resources. Hyperlinks to projects are thus both human readable and machine readable, and increase the likelihood that individual repositories of projects won't become walled gardens.||Multiple representations, at least including human readable HTML and some sematic format.|
|1||Version URL||Each version of this project should have a unique URL. This is what uniquely identifes a given model of a given project.||OSHW-ProjectName-Hardware-Version|
|Fork Parent URL||If this project is a fork of another project, this provides the project and version number that it is forked from.||Does this replicate what "geneology" is trying to achieve? The suggestion here is that we refer to parent projects but not child projects, it's their job to refer to us.|
|1||2||Name||Clearly state the hardware's name, avoid confusion with other similar projects and infrigements of trademarks.||Text||N/A|
|1||3||Description||Textual description of the hardware. Include link to Google Translate.||Text||N/A||Required|
|4||Hardware Version||State the hardware's version in a highly visible place.|
Optional: indicate date of release.
Ex: V4 - Dec 18, 2012
|Required for unique identification. use http://semver.org/ for semantic versioning guidelines||Text||N/A||Required|
|5||Software Version||State the software's version in a highly visible place.|
Optional: indicate date of release.
Ex: V4 - Dec 18, 2012
|Required for unique identification.||Text||N/A||Required - Project Specific (PS) - (note: Project Specific means that not all artifacts will have this documentation item)|
|1||6||Hardware License||State the hardware's open source license and link to license page.|
Ex: CC BY-SA
|7||Software License||State the software's open source license and link to license page.|
|8||Attribution||Identify the authors and contributors. Identify Active Team Members. Optional: state how you'd like the authors to be credited.||Gives credit and respect to creators of the work, which is important to some for reasons of reputation.|
Many licenses compatible with the OSHW definition require attribution, so information about its authors and contributors is an essencial component of OSHW documentation.
Allows developer to contact authors for further development.
|9||Open Source Label||Graphic indicating which layers of the design are open source. Place in very prominant area (eg. product's home page).|
Ex: Electronics: open; Mechanics: closed; Software: closed; Hydraulics: open.; Materials: closed (ex., for special steel alloy).
|File||PNG, GIF, JPG||N/A||Required||Create Open Source Label Gaphic: identify all possible layers, create graphic, propose community-wide adoption.||OSHWA|
|10||Graphical Representation||Provide hi-res images of the hardware, preferably allowing zooming and 3D rotation. Use a real picture or a computer model.||Provides clear reality check of what the artifact is.||File||Vector drawing, hi-res photo, 3D model, video, 3D animation.||N/A||Optional|
|11||Status Brief||State the level of completion of the Hardware, active problem that is currently being solved, and future development intentions. Describe known issues. Burndown graph would be useful.|
Ex: Hardware: complete; Software: complete; Documentation: incomplete; Enterprise: product shipping, open business model. Next steps: robustness improvements to allow for 100 hours of unattended operation.
|It should be apparent immediately from the front page of a product how well a given device works, (1) for potential replicators - to assess the value of replicating by understanding how well the machine works, (2) for developers - to understand what needs improvement, and (3) economic development - what is the true economic significance? What is the basic assessment of cost and performance?|
This information is typically missing - but to foster an increase in development velocity and to motivate otehrs to help - transparency on the actual status is critical. Such transparency builds trust between the development team and potential new developers. Absence of this information is a significant deterrent to collaborative development, as people need to assess the status of a project properly before getting involved.
|12||Change Log||List of changes/upgrades since last version of the design.||Text||N/A||Required|
|13||Specifications||List the hardware's specifications.|
Ex: for OSE - OSE Specifications are followed
|Text||N/A||Required||Specifications||For development, one must start with desired specifications. These determine the direction of development.|
|14||Compatibility||State what other peices of hardware the design is compatible with.|
Ex: Arduino Leonardo
|Text||N/A||Optional||Product Ecology Analysis||This is an analysis of how an artifact fits with other products of a desired set.|
|15||Dependency||State what other types of hardware or software are necessary to use the hardware during normal operation, during building, during assembly, during testing, and during de-assembly.|
Ex: 5V Power Supply, Ethernet Shield
|16||Geneology||Provide information on the hardware's origins, derivatives and replications. Copy this from the previous version and include your new version.||Note that in hardware projects, each build is a fork - ie, a physical manifestation in itself. Therefore, each version should be documented. In software, typically the latest version is documented.||File||Timeline||http://timeline.verite.co/||Optional|
|17||Human Factors & Usability Overview||State general considerations for user-friendliness and performance, such as: (1), whether a machine is 'turnkey,' or whether one has to make numerous adjustments prior to use. Time/procedure required prior to turn-on. (2) Comfort and extras - ex. a cushioned driver's seat that is indispensible for long-time use; lights for night-time use; air-tight cab for a car in cold winter, etc. (3) Unattended operation vs. necessity to watch the machine or make constant adjustements; (4) Quality of result obtained - while Specifications (above) provide quantitative assessment, a quick overview of qualitative performance is useful to assess value of replicating the machine, such as: rough edges are left after a cut with the machine; 'the machine is unbearably so', or 'the machine works equivalent to or better than any commercial counterpart based on speed and quality of resulting product.'||Text||N/A||Optional|
|18||Related Projects||List related projects. If done properly, this has the potential to spawn collaboration between similar projects.|
Ex: Local Motors, Wikispeed for OS Car project.
|Helps foster collaboration between projects.||Text||N/A||Optional||Analysis of industry standards||Industry standards - are example of other existing hardware that may or may not be in the marketplace already. For developing any product, it is useful to guide development based on what already exists in the marketplace. This is a starting point of ideas for development. Performance baselines are established from an analysis of industry standards.|
|19||Related Resources||List related resources such as other tutorials, similar projects, wikipedia pages, etc.||Text||N/A||Optional|
|20||Tags||List tags that best decsribe the device/design. Make sure to include OSHW.|
|Keywords||N/A||Optional||Develop taxonomy of tags|
|21||Replication Map||Show locations of all machines in use to keep track of the evolution of the project.||Optional|
|22||Communication Channels||List media of communication, such as Website, Blogs, Wikis, Databases, Support Platform, Google Groups, Facebook Groups, Twitter feed, hashtag, forums, Stack Overflow, email addresses, chats, texting, phone numbers, and other venues of development. Optionally, include notes on how to communicate effectively.||Clear communication channels should be maintained for documentation development.||Required||Invitation, signup and database of participants needs to be established|
|23||Explainer Video||Produce a scripted animation or video showing how the artifact works, why it is important, and otherwise motivate users to engage with the artifact. Show context for how this artifact fits with a greater ecosystem of OSHW. Make this video 2 minutes or under.||Explainer videos can accelerate development velocity drastically - by motivating others through clear understanding of potential benefits.||video||Optional|
|24||Repository||Link to repositories of project files. (git, hg, etc.)||Required|
|26||Difficulty Level||State the difficulty level for building the device.|
Ex: Intro Level, Intermediate, Advanced
|27||Time Required||State the approximate time required to build the device.|
Ex: 2 days.
|28||Tools Required||List the tools needed to build the device.|
Ex: laser cutter, welder, soldering iron.
|29||Space Required||Indicate the space required to build the device.|
Ex: 1000 sf workshop
|30||Skills Required||Indicate what skills are required to build the device.|
Ex: welding, laser cutting.
|31||Cost||Include a budget for the project and state the total cost of materials and components.||Text||N/A||Optional|
|32||Safety & Health||Warnings on any dangers or risks associated with the build of the artifact - such as risk of injury from moving parts, heavy objects, potential accidents, chemical dangers, fumes, etc..||If a builder is inexperienced, basic considerations for safety must be included to promote a safe and responsible build.||N/A||Required|
|33||Ergonomics||State the expected time for the build of the artifact. Provide suggestions on effective build process to minimize effort and maximize comfort of the builder. Do this analysis for different production routes used - such as by hand vs. by utilizing automation.||It is useful to document the time requirements for a build to help a builder understand the level of commitment required, and therefore help the builder make an informed decision on whether building something is worth the effort.||Text||N/A||Optional|
|35||Materials & Components|
|36||Bill of Materials (BOM)||BOM's and all parts lists should include unique identifiers: item name*, item description*, quantity*, dimensions/package*, suppliers* part number, link to datasheet, image, price, notes. (*required fields)|
Provide information on alternative materials and components whenever possible. Ex: if carbon fiber is not available use punched aluminum. Prefer listing hardware project names based on their semantic versioning name so that they can be automatically found and re-used by software.
|Text / File||Text for less than 10 items|
Spreadsheet if more than 10 items: CSV, XLS, Google Spreadsheet.
In addition to spreadsheet: CAD-integrated or add-on BoM management tool.
|STEP external references||Required|
|39||Conceptual Design||Conceptual design is the type of design that describes general working principles and outlines main components of an artifact, without necessarily providing dimensionally-correct design of the artifact. Show all the critical parts and modules||Conceptual design allows one to understand the scope of all the parts of an artifact. Understanding conceptual design is critical for modifying afrtifacts, but it's not critical for an identical replica of the artifact.||Image||Google Doc, Google Sketchup,||Optional||Conceptual design review||Review Team and process must be established for effective review beginning at the concept level.|
|40||Conceptual Interface Design||It is assumed that artifacts are built on module-based design. Show a diagram of an interface prior to that interface being built.||Prior to a rigorous design being generated, conceptual designs serve as a placeholder.||Optional|
|41||Labeled Diagram||This is the actual labeled design - a step above the Concept Design. The labeled diagram may be a CAD or real picture, and it should include different angles. Diagram should label components.||Artifacts should be labeled so that a novice can understand the artifact quickly.||Image|
|42||Digital Fabrication Files||Provide digital fabrication files for download in at least one but preferably more standard formats.|
Provide previews of digital fabrication files.
|File||Digifab: PDF + DXF for subtractive manufacturing, STL + Google SketchUp + SCAD for additive manufacturing.|
Previews: 2D (PDF, BMP, PNG, GIF, JPG) and 3D (embeded STL, Google Sketchup, etc.)
|http://sketchfab.com/faq#embed for STL files. Google Warehouse.||Required PS|
|43||Module Diagram||Shows the breakdown of the Artifact into modules. Does not have to show components of modules - as the Labeled Diagram already contains this.||File|
|44||Exploded View Drawing||http://en.wikipedia.org/wiki/Exploded_view_drawing . Use 3D or isometric drawings as appropriate.||Useful for understanding how artifacts are put together.||Source file: BMP, PNG, GIF, JPG. PDF ok but not modifiable.||Required PS||Develop partnership with Wikipedia or similar pipeline to assure reliable generation of Exploded View Drawings|
|45||3D CAD||Provide 3D CAD of the object, and applies to all 3-dimensional artifacts. Use a commonly accessible platform such as Sketchup in preference to less accessible, proprietary software. Include tolerance information, as discussed at http://opensourceecology.org/wiki/Geometric_Dimensioning_and_Tolerancing||2-dimensional drawings are generated from 3D CAD.||File||STEP file||Required PS||Design Review||Review Team and process must be established for effective review of actual design. Effective review indicates use of a generally-accessible 3D CAD platform, as well as ability to share snapshots of an artifact in a universally-viewable format.|
|45.5||3D preview||Provide a preview of all parts in 3D.||Reviewer should have easy access for reviewing designs without requiring access to special software outside of a web browser.|
|46||3D Scan||If CAD is not available, provide a 3D scan of an artifact.||A 3D scan, when processed properly, could be used to generate a full 3D design.||Optional|
|47||Engineering Drawings||Engineering drawings are technical drawings used to fully describe the requirements of engineered items. For machines, this is fabrication drawings.||To go from concepts to replicability without guesswork, full specification is required.||Required PS||Standards are not published freely. See http://opensourceecology.org/wiki/Geometric_Dimensioning_and_Tolerancing||who|
|48||Fabrication Drawings||A special type of engineering drawing used for mechanical devices.||Required PS|
|48.5||2D Preview||Embed the complete design files for a preview of the design.||Provide for easy reviewability of designs without requiring special software to open files.|
|49||Wiring, Cable Routing, Hose Routing Diagram||Layout of flexible or stiff conduits of all sorts (wires, hoses, airlines, etc) should be provided.||Functionality is improved with clean routing of various types of conduits.||optional|
|50||Electronics||Provide hi-res electronics schematics (symbolic representation of the circuit, showing how to connect the components).|
Provide PCB layout (concrete representation of the circuit, used to fabricate PCBs).
Provide preview of schematics.
|File||Schematics: preferably in hi-res PDF, BMP, PNG, GIF, JPG. Other formats: Eagle, Altium, KiCad, gEDA, BRL-CAD, Fritizing.|
PCB: In vector artwork format preferably as Gerber/Excellon and PDF.
Preview of schematics: PDF, BMP, PNG, GIF, JPG.
|51||Process Design||Produce a design of a process, such as chemical processing. Include all steps, retention times, substances used, etc. Document toolchain in a flowchart.||text, image||Flowchart + Text||Required PS|
|52||Hydraulics & Pneumatics||Provide a diagram of hydraulic design. Use standard hydraulic symbols, as in http://opensourceecology.org/wiki/Hydraulic_Circuit_Design||Required PS|
|53||Electromagnetic Diagram||Provide field lines involved in magnetic devices.||Optional|
|54||Optical Diagrams||Provide optical diagrams - such as ray tracing or focal lengths - for optical systems.||image||Required PS|
|55||Design Rationale||Explanation of why certain design decisions were made for the artifact. Document why you chose one design over another, with reference to Analysis of Industry Standards||Together with a Genealogy, this explains a context for how design choices were made and how they evolved.||text||Optional||Design Rationale Review||Review at the phase of Design Rationale is important to get a project going on the right footing.|
|56||Calculations||Calculations are required to understand the performance of a machine. These could be power, thermal, force, stress, hydraulics, flow, speed, structural, electromagnetic, or other calculations. This includes Computer Aided Engineering (CAE) analysis such as Finite Element Analysis (FEA). Document any derived quantities. Document online calculator/design resources.||Documented calculations allow others to verify and optimize performance. Not required for replication, but is required for modification of artifact.||Optional.||Calculation Review||It is useful to verify performance and cost calculations.|
|57||Physics of Why It Works||Explanation of first principles involved in the functioning of the machine.||Optional|
|58||Logic Design||Document operating step sequencing and any other logic model required for the operation of the artifact.||Logic is typically not immediately discernable. Documentation of logic design allows one to gain this understanding.||Optional|
|59||Animated Model||Animation showing functional mechanism.||This provides clear visual understanding of machine functioning, build processes, workflows, and others. It is also useful in video documentation.||video||MOV, MP3, FLV, animated GIF, etc.||Optional|
|60||Design Review||Documented reviews of a design. Design review can be general or specific.||Review allows for input from subject matter experts to fill in design gaps. During the development phase, review should be ongoing. The documentation platform should capture only the most important results.||text||Optional|
|61||Failure Modes and Effects Analysis||Analize a design prior to the build for possible failures and document this analysis, including solutions.||Predicting mistakes is cheaper than making mistakes.||Optional|
|61.5||3D Diffs||Show the difference between versions of the artifact in 3D representation.||It should be easy to put 2 versions side by side to observe differences.||3D image||Optional|
|63||Source Code||Provide annotated source code, including code logic. Ex., describe brick pressing logic based on physical structure and function of CEB machine.||File||Text file, Repository, Zip||Required PS|
|64||Firmware||Provide firmware.||File||Text file, Repository, Zip||Required PS|
|65||Instructions||Provide instructions for running, installing, compiling, etc.||Text||Required PS|
|66||Libraries||Provide any libraries or links to libraries that are needed||File / Link||Required PS|
|68.5||Infrastructure Requirements||List the space, power, tooling, timing, environment, and other requirements for the build to occur.|
|69||Tool List||List tools used in production of Artifact.||Required|
|70||Jig Design||Show designs of any jigs used in production, and document procedures for using these jigs.||text, image, videos|
|71||Machine Settings||Describe fabrication/production procedures, including suggested machine settings (ex: laser cutter settings, mixing time for cement mixer)||Text||Required PS|
|72||Assembly||Provide set-by-step instructions on how to assemble the Product (from raw materials, parts and/or modules) using either:|
- Clear, hi-res images accompanied by clear textual instructions (include link to Google Translate).
- IKEA-style visual instructions
|Text + File||PNG, GIF, JPG||Required PS||Develop a visual language for OSHW|
|72.5||Assembly Video||Produce a video of artifact assembly and disassembly.|
|73||Procedure||Provide step-by-step sequence of instructions on how to make Products. This could be a process (for materials), fabrication procedure (for components), procedure (for building) using:|
- Clear, hi-res images accompanied by clear textual instructions (include link to Google Translate).- IKEA-style visual instructions - others.
|Text + File||PNG, GIF, JPG||Required||Develop a visual language for OSHW|
|74||Instructional Video||Provide step-by-step video documentation.||While not necessary, this helps people understand build procedures.||Optional|
|75||Quality Control||Procedure for testing the artifact build throughout the fabrication process. Define, execute, and document this procedure.||Optional|
|75.5||Integration Checklist||List cosiderations that have to be taken when putting all modules together.||Optional|
|77||Rapid Prototyping||Make scale models of artifacts with a laser cutter and 3D printer to test out parts fit and other issues. Document the build instructions and results of prototype builds.||Scale models allow one to test a design prior to a complete build.||text and images||Optional|
|78||Test Design||Design and document a testing procedure and protocol for a finished design.||text||Optional|
|79||Data Collection||Collect performance data on the artifact. Discuss how the data was obtained.||text||Required|
|80||Safety Issues||Make careful observations about any safety concerns of using the artifact, and document these.||Safety is an important concern for any user.||text, image, video||Required|
|81||Known Bugs||Make an exhaustive list of any known issues about the artifact.||Required|
|82||Destructive Testing||Test the artifact to its failure limit and gather performance data until that point. Discuss the point of failure.||Actual limits of an artifact are not known unless empirical data is obtained.||Optional|
|82.5||Product Certification||Provide official test data and certification from professional standards associations.||Accepted standards may be a good benchmark of performance.|
|84||Operation||Startup, operating, calibration instructions.||Required|