OSHW Documentation Taxonomy Items

	A	B	C	D	E	F	G	H	I	J	K	L	M	N	O
1
2			oManual Standard	http://cl.ly/3i0C0O0a1s0e
3			oManual Schema	https://github.com/iFixit/omanual
4			oProject Schema	https://github.com/kurttomlinson/oProject
5			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
6
7	Voting	1	Device Dashboard
8	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.
9	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
10			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.
11	1	2	Name	Clearly state the hardware's name, avoid confusion with other similar projects and infrigements of trademarks.			Text		N/A
12	1	3	Description	Textual description of the hardware. Include link to Google Translate.			Text		N/A	Required
13		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
14		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)
15	1	6	Hardware License	State the hardware's open source license and link to license page. Ex: CC BY-SA			Text		N/A	Required
16		7	Software License	State the software's open source license and link to license page. Ex: GPL			Text		N/A	Required PS
17		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.	Text		N/A	Required
18		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
19		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
20		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.	Text		N/A	Required
21		12	Change Log	List of changes/upgrades since last version of the design.			Text		N/A	Required
22		13	Specifications	List the hardware's specifications. Ex: http://www.ladyada.net/make/tvbgone/ 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.
23		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.
24		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			Text		N/A	Optional
25		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
26		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
27		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.
28		19	Related Resources	List related resources such as other tutorials, similar projects, wikipedia pages, etc.			Text		N/A	Optional
29		20	Tags	List tags that best decsribe the device/design. Make sure to include OSHW. Ex: OSHW-Shield-Arduino-Electronics.			Keywords		N/A	Optional	Develop taxonomy of tags
30		21	Replication Map	Show locations of all machines in use to keep track of the evolution of the project.						Optional
31		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
32		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
33		24	Repository	Link to repositories of project files. (git, hg, etc.)						Required
34		25	Build Dashboard
35		26	Difficulty Level	State the difficulty level for building the device. Ex: Intro Level, Intermediate, Advanced			Text		N/A	Optional
36		27	Time Required	State the approximate time required to build the device. Ex: 2 days.			Text		N/A	Optional
37		28	Tools Required	List the tools needed to build the device. Ex: laser cutter, welder, soldering iron.			Text		N/A	Required
38		29	Space Required	Indicate the space required to build the device. Ex: 1000 sf workshop			Text		N/A	Optional
39		30	Skills Required	Indicate what skills are required to build the device. Ex: welding, laser cutting.			Text		N/A	Optional
40		31	Cost	Include a budget for the project and state the total cost of materials and components.			Text		N/A	Optional
41		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
42		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
43
44		35	Materials & Components
45		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
46		37
47		38	Designs
48		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.
49		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
50		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
51		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
52		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
53		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
54		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.
55		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.
56		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
57		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
58		48	Fabrication Drawings	A special type of engineering drawing used for mechanical devices.						Required PS
59		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.
60		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
61		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. Ex: http://arduino.cc/en/Main/arduinoBoardDuemilanove			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.		Required PS	s
62		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
63		52	Hydraulics & Pneumatics	Provide a diagram of hydraulic design. Use standard hydraulic symbols, as in http://opensourceecology.org/wiki/Hydraulic_Circuit_Design						Required PS
64		53	Electromagnetic Diagram	Provide field lines involved in magnetic devices.						Optional
65		54	Optical Diagrams	Provide optical diagrams - such as ray tracing or focal lengths - for optical systems.			image			Required PS
66		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.
67		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.
68		57	Physics of Why It Works	Explanation of first principles involved in the functioning of the machine.						Optional
69		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
70		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
71		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
72		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
73		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
74		62	Software
75		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
76		64	Firmware	Provide firmware.			File	Text file, Repository, Zip		Required PS
77		65	Instructions	Provide instructions for running, installing, compiling, etc.			Text			Required PS
78		66	Libraries	Provide any libraries or links to libraries that are needed			File / Link			Required PS
79		67
80		68	Build Instructions
81		68.5	Infrastructure Requirements	List the space, power, tooling, timing, environment, and other requirements for the build to occur.
82		69	Tool List	List tools used in production of Artifact.						Required
83		70	Jig Design	Show designs of any jigs used in production, and document procedures for using these jigs.			text, image, videos
84		71	Machine Settings	Describe fabrication/production procedures, including suggested machine settings (ex: laser cutter settings, mixing time for cement mixer)			Text			Required PS
85		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
86		72.5	Assembly Video	Produce a video of artifact assembly and disassembly.
87		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
88		74	Instructional Video	Provide step-by-step video documentation.		While not necessary, this helps people understand build procedures.				Optional
89		75	Quality Control	Procedure for testing the artifact build throughout the fabrication process. Define, execute, and document this procedure.						Optional
90		75.5	Integration Checklist	List cosiderations that have to be taken when putting all modules together.						Optional
91		76	Testing
92		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
93		78	Test Design	Design and document a testing procedure and protocol for a finished design.			text			Optional
94		79	Data Collection	Collect performance data on the artifact. Discuss how the data was obtained.			text			Required
95		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
96		81	Known Bugs	Make an exhaustive list of any known issues about the artifact.						Required
97		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
98		82.5	Product Certification	Provide official test data and certification from professional standards associations.		Accepted standards may be a good benchmark of performance.
99		83	User Manual
100		84	Operation	Startup, operating, calibration instructions.						Required