OSHW Documentation Taxonomy Items
The version of the browser you are using is no longer supported. Please upgrade to a supported browser.Dismiss

oManual Standardhttp://cl.ly/3i0C0O0a1s0e
oManual Schemahttps://github.com/iFixit/omanual
oProject Schemahttps://github.com/kurttomlinson/oProject
Taxonomy ItemGuidelinesEx.Rationale for GuidelineFormatRec. File TypeSuggested ToolsPriorityDevelopment TasksWhoDevelopment Platform ItemGuidelines and RationaleSuggested Tool
Voting1Device Dashboard
1Project URLA 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.
1Version URLEach 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 URLIf 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.
12NameClearly state the hardware's name, avoid confusion with other similar projects and infrigements of trademarks.TextN/A
13DescriptionTextual description of the hardware. Include link to Google Translate.TextN/ARequired
4Hardware VersionState 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 guidelinesTextN/ARequired
5Software VersionState the software's version in a highly visible place.
Optional: indicate date of release.
Ex: V4 - Dec 18, 2012
Required for unique identification.TextN/ARequired - Project Specific (PS) - (note: Project Specific means that not all artifacts will have this documentation item)
16Hardware LicenseState the hardware's open source license and link to license page.
7Software LicenseState the software's open source license and link to license page.
TextN/ARequired PS
8AttributionIdentify 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.
9Open Source LabelGraphic 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).
FilePNG, GIF, JPGN/ARequiredCreate Open Source Label Gaphic: identify all possible layers, create graphic, propose community-wide adoption.OSHWA
10Graphical RepresentationProvide 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.FileVector drawing, hi-res photo, 3D model, video, 3D animation.N/AOptional
11Status BriefState 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.
12Change LogList of changes/upgrades since last version of the design.TextN/ARequired
13SpecificationsList the hardware's specifications.
Ex: http://www.ladyada.net/make/tvbgone/
Ex: for OSE - OSE Specifications are followed
TextN/ARequiredSpecificationsFor development, one must start with desired specifications. These determine the direction of development.
14CompatibilityState what other peices of hardware the design is compatible with.
Ex: Arduino Leonardo
TextN/AOptionalProduct Ecology AnalysisThis is an analysis of how an artifact fits with other products of a desired set.
15DependencyState 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
16GeneologyProvide 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.FileTimelinehttp://timeline.verite.co/Optional
17Human Factors & Usability OverviewState 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.'TextN/AOptional
18Related ProjectsList 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.TextN/AOptionalAnalysis of industry standardsIndustry 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.
19Related ResourcesList related resources such as other tutorials, similar projects, wikipedia pages, etc.TextN/AOptional
20TagsList tags that best decsribe the device/design. Make sure to include OSHW.
Ex: OSHW-Shield-Arduino-Electronics.
KeywordsN/AOptionalDevelop taxonomy of tags
21Replication MapShow locations of all machines in use to keep track of the evolution of the project.Optional
22Communication ChannelsList 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.RequiredInvitation, signup and database of participants needs to be established
23Explainer VideoProduce 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.videoOptional
24RepositoryLink to repositories of project files. (git, hg, etc.)Required
25Build Dashboard
26Difficulty LevelState the difficulty level for building the device.
Ex: Intro Level, Intermediate, Advanced
27Time RequiredState the approximate time required to build the device.
Ex: 2 days.
28Tools RequiredList the tools needed to build the device.
Ex: laser cutter, welder, soldering iron.
29Space RequiredIndicate the space required to build the device.
Ex: 1000 sf workshop
30Skills RequiredIndicate what skills are required to build the device.
Ex: welding, laser cutting.
31CostInclude a budget for the project and state the total cost of materials and components.TextN/AOptional
32Safety & HealthWarnings 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/ARequired
33ErgonomicsState 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.TextN/AOptional
35Materials & Components
36Bill 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 / FileText 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 referencesRequired
39Conceptual DesignConceptual 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 modulesConceptual 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. ImageGoogle Doc, Google Sketchup, OptionalConceptual design reviewReview Team and process must be established for effective review beginning at the concept level.
40Conceptual Interface DesignIt 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
41Labeled DiagramThis 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
42Digital Fabrication FilesProvide digital fabrication files for download in at least one but preferably more standard formats.

Provide previews of digital fabrication files.
FileDigifab: 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
43Module DiagramShows the breakdown of the Artifact into modules. Does not have to show components of modules - as the Labeled Diagram already contains this.File
44Exploded View Drawinghttp://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 PSDevelop partnership with Wikipedia or similar pipeline to assure reliable generation of Exploded View Drawings
453D CADProvide 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_Tolerancing2-dimensional drawings are generated from 3D CAD.FileSTEP fileRequired PSDesign ReviewReview 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.53D previewProvide 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.
463D ScanIf 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
47Engineering DrawingsEngineering 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 PSStandards are not published freely. See http://opensourceecology.org/wiki/Geometric_Dimensioning_and_Tolerancingwho
48Fabrication DrawingsA special type of engineering drawing used for mechanical devices.Required PS
48.52D PreviewEmbed the complete design files for a preview of the design. Provide for easy reviewability of designs without requiring special software to open files.
49Wiring, Cable Routing, Hose Routing DiagramLayout 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
50ElectronicsProvide 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.

Ex: http://arduino.cc/en/Main/arduinoBoardDuemilanove
FileSchematics: 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.
Required PSs
51Process DesignProduce a design of a process, such as chemical processing. Include all steps, retention times, substances used, etc. Document toolchain in a flowchart.text, imageFlowchart + TextRequired PS
52Hydraulics & PneumaticsProvide a diagram of hydraulic design. Use standard hydraulic symbols, as in http://opensourceecology.org/wiki/Hydraulic_Circuit_DesignRequired PS
53Electromagnetic DiagramProvide field lines involved in magnetic devices.Optional
54Optical DiagramsProvide optical diagrams - such as ray tracing or focal lengths - for optical systems.imageRequired PS
55Design RationaleExplanation of why certain design decisions were made for the artifact. Document why you chose one design over another, with reference to Analysis of Industry StandardsTogether with a Genealogy, this explains a context for how design choices were made and how they evolved.textOptionalDesign Rationale ReviewReview at the phase of Design Rationale is important to get a project going on the right footing.
56CalculationsCalculations 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 ReviewIt is useful to verify performance and cost calculations.
57Physics of Why It WorksExplanation of first principles involved in the functioning of the machine.Optional
58Logic DesignDocument 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
59Animated ModelAnimation showing functional mechanism.This provides clear visual understanding of machine functioning, build processes, workflows, and others. It is also useful in video documentation.videoMOV, MP3, FLV, animated GIF, etc.Optional
60Design ReviewDocumented 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.textOptional
61Failure Modes and Effects AnalysisAnalize a design prior to the build for possible failures and document this analysis, including solutions.Predicting mistakes is cheaper than making mistakes.Optional
61.53D DiffsShow 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 imageOptional
63Source CodeProvide annotated source code, including code logic. Ex., describe brick pressing logic based on physical structure and function of CEB machine.File Text file, Repository, ZipRequired PS
64FirmwareProvide firmware.File Text file, Repository, ZipRequired PS
65InstructionsProvide instructions for running, installing, compiling, etc.TextRequired PS
66LibrariesProvide any libraries or links to libraries that are neededFile / LinkRequired PS
68Build Instructions
68.5Infrastructure RequirementsList the space, power, tooling, timing, environment, and other requirements for the build to occur.
69Tool ListList tools used in production of Artifact.Required
70Jig DesignShow designs of any jigs used in production, and document procedures for using these jigs.text, image, videos
71Machine SettingsDescribe fabrication/production procedures, including suggested machine settings (ex: laser cutter settings, mixing time for cement mixer)TextRequired PS
72AssemblyProvide 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 + FilePNG, GIF, JPGRequired PSDevelop a visual language for OSHW
72.5Assembly VideoProduce a video of artifact assembly and disassembly.
73ProcedureProvide 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 + FilePNG, GIF, JPGRequiredDevelop a visual language for OSHW
74Instructional VideoProvide step-by-step video documentation.While not necessary, this helps people understand build procedures.Optional
75Quality ControlProcedure for testing the artifact build throughout the fabrication process. Define, execute, and document this procedure.Optional
75.5Integration ChecklistList cosiderations that have to be taken when putting all modules together.Optional
77Rapid PrototypingMake 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 imagesOptional
78Test DesignDesign and document a testing procedure and protocol for a finished design.textOptional
79Data CollectionCollect performance data on the artifact. Discuss how the data was obtained.textRequired
80Safety IssuesMake careful observations about any safety concerns of using the artifact, and document these.Safety is an important concern for any user.text, image, videoRequired
81Known BugsMake an exhaustive list of any known issues about the artifact.Required
82Destructive 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.5Product CertificationProvide official test data and certification from professional standards associations.Accepted standards may be a good benchmark of performance.
83User Manual
84OperationStartup, operating, calibration instructions.Required