Difference between revisions of "A guide to Open Source Hardware"

From OPEN! - Wiki
Jump to: navigation, search
Line 1: Line 1:
==Preamble==
+
==Note==
What does the term "source" refer to in "Open Source Hardware"? In the case of software it is pretty clear that the source code is made publicly available so you can call a software "open source". For hardware, this is less clear, especially in the case of mechanical products. According to the Open Source Hardware Association (OSHWA): "''Open source hardware is hardware whose design is made publicly available so that anyone can study, modify, distribute, make, and sell the design or hardware based on that design.''" [http://www.oshwa.org/sharing-best-practices/] What does it mean to "make a design publicly available"? What are the documents that enable others to study, distribute, make or sell your design?
+
The latest version of this document can be found on [https://github.com/jbon/Best-Practices-of-Open-Source-Mechanical-Hardware/blob/master/Best%20Practices%20of%20Open%20Source%20Mechanical%20Hardware.md GitHub], open for collaboration and improvement.
 +
It can also be accessed via [http://dx.doi.org/10.14279/depositonce-5729 DepositOnce].
  
This document, particularly addressed to projects developing open source ''mechanical'' hardware products, will help you answer these questions for your product.
+
==Practical advice for sharing product-related documentation==
  
==Preliminary step: make a short self-assessment==
+
What makes a software program “open source” is that its source code is publicly available. What is pretty clear for software is less clear for hardware—especially for mechanical hardware. What does the term "source" refer to in "open source hardware"? According to the Open Source Hardware Association (OSHWA): ''"Open source hardware is hardware whose design is made publicly available so that anyone can study, modify, distribute, make, and sell the design or hardware based on that design."'' [http://www.oshwa.org/definition/ •]  What does it mean to "make a design publicly available"? What are the documents that enable others to study, distribute, make or sell a design? This short guide provides practical answers to these questions and is dedicated to those who want to make a piece of mechanical hardware open source.  
What kind of information you may want to share with your community basically depends on two things:
 
* What motivates your intention to go open source. Do you want to make your product open source so your customers can see how your product is made? Do you want your innovative product to be replicated by other makers or producers? Do you want others to give you feedback or even to take part in your product development project?
 
* Your current state of product development. The documents, and level of detail (e.g. concept sketches vs. production drawings) may vary from the beginning to the end. So if you want to go open source before your product is fully defined, you may need to share other documents than 3D Models or construction drawings.
 
  
Once these first questions have been answered, this document will explain how to share your documents accordingly.
+
==Preamble==
 +
The above cited definition implies four degrees of freedoms regarding a considered piece of hardware:
 +
* Freedom to study: i.e. the right to access enough information to understand how the piece of hardware (referred herein as the product) works and to retrace the logic behind its design;
 +
* Freedom to modify: i.e. the right to edit the product definition documents and to tweak or develop the product further for any purpose;
 +
* Freedom to make: i.e. the right to use the product definition documents to manufacture the piece of hardware;
 +
* Freedom to distribute: i.e. the right to share or sell the product definition documents as well as the physical products fabricated according to these documents.
 +
A precondition for the realization of these degrees of freedom is that hardware must be released with its “source code”, which is termed in the referred definition as “documentation” or “design files”. However, what information has to be shared in order to allow any interested person to study, modify, make and distribute a piece of mechanical hardware—in other words, what is the source of open source mechanical hardware—is a question that is not trivial and remains unanswered in this definition.
 +
While sharing a CAD file would allow anyone to study the product design, this may be insufficient information to manufacture it. While sharing fully defined and detailed assembly instructions would allow anyone with sufficient production means and knowhow to manufacture the product, this may be insufficient to allow them to participate in the further design of the product. Is a product open source as soon as enough documentation is provided to ensure one of these freedoms? Or is it mandatory to provide enough documentation so that all of these freedoms are ensured? Is it enough to publish CAD files or is it mandatory to equally share assembly instructions?
 +
In the absence of clear answers to these questions, this guide strives to provide practical advice on information you may want to share with your community in order to make your piece of mechanical hardware open source. It shows what you can do, but does not pretend telling what you must do. It is based on the practical assumption that the type of information you may want to share depends on your motivation to go open source:
 +
* Is your motivation to demonstrate your customers how good your product is designed? Then put particular emphasis on publishing detailed and commented design files. See section “enable others to study your product”.
 +
* Do you want your innovative product to be manufactured by others so it can be rapidly adopted worldwide? Then put particular emphasis on publishing clear assembly instructions and a parts list. See section “enable others to make your product”.
 +
* Do you want to use open source as a means to improve your product by receiving feedback from others to or by even letting them take part in your product development project? Then put particular emphasis on publishing documents others can edit and tell potential contributors what you expect from them. See section “enable others to contribute to your design”.
 +
Note that the maturity of your product also influences the content and the level of detail of your product documentation. If you are still at an early design phase, you may have only some description of the product concept and requirements in the form of sketches and text. If your product is fully defined, you may have complete CAD drawings and a stable parts list. But independent from the maturity of your design, the general rule of thumb is to share the information you have at the time you have it.
 +
In the following, the possible components of making your product open source are presented.
 +
This document is to be considered as complementary to the [http://www.oshwa.org/sharing-best-practices/ best practices of open source hardware] published by the Open Source Hardware Association .
  
 
==Enable others to study your product==
 
==Enable others to study your product==
If your motivation for going open source is to allow others to study your product, then you may want to publish your design files, i.e. the files you created to define your product. Design files are for example 2D drawings or 3D models, circuit board layouts, schematics or additional technical drawings that show the structure of your product in detail. Sharing these files will allow others to understand how your product is designed in detail.
+
If your motivation for going open source is to allow others to study your product, then you may want to publish your design files, i.e. the files you created to define your product. Design files are for example 2D drawings or 3D models, circuit board layouts, schematics or additional technical drawings that show the structure of your product in detail. Sharing these files will allow others to understand how your product is designed. In the best case, you will share your design files in their '''original format''', that is, in the format in which you created them. Even better is to use free and open-source software applications and open file formats so that others do not have to buy expensive licenses to access the information you are sharing with them.
In the best case you will share your design files in their '''original format''', that is, in the format in which you created them. Even better is to use free and open-source software applications and open file formats so that others don’t have to buy expensive licenses to access the information you are sharing with them.
+
Alternatively, you can share your design files in '''export file formats''' such as STL, PDF or PNG. Exporting your original files in those formats will however inevitably lead to loss of information. Therefore, sharing these files shall only be considered as additional measure, for example in cases you are using costly software that others may not be able to afford.  
  
Alternatively, you can share your design files in '''export file formats''' such as STL, PDF or PNG. Exporting your original files in those formats will however inevitably lead to loss of information. Therefore, sharing these files shall be only considered in cases you are using costly software that others may not be able to afford.
 
 
In any case you may:
 
In any case you may:
 
* share these files in a design repository to allow others to browse your files online (e.g. GitHub);
 
* share these files in a design repository to allow others to browse your files online (e.g. GitHub);
 
* give the possibility to download packaged files in one click;
 
* give the possibility to download packaged files in one click;
* clearly separate original design files and exports and label them accordingly.
+
* clearly separate original design files and exports by labelling them accordingly.
  
 
==Enable others to replicate your product==
 
==Enable others to replicate your product==
If you want others to replicate your product, you may think about publishing a part list and assembly instructions. Below are you will find some recommendations regarding these two elements.
+
If you want others to replicate your product, you may publish a parts list and assembly instructions. Below, you will find some recommendations regarding these two elements.  
 +
 
 +
===Share a parts list===
 +
A well-made and clear parts list (also termed as bill of materials [BOM] in engineering jargon) is an essential document for those who want to replicate your product. This document will help them understand which parts they have to source or manufacture before assembling your product. The [http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=43883 ISO 7573:2008] standard provides a list of "minimum requirements for parts lists" and may help you with setting up your BOM properly. Unfortunately this document is not open source and not everybody can access it freely. Here is some advice about how to structure your BOM.
 +
A BOM may contain the following information for each part/component of your product:
  
===Part list===
 
A well-made and clear part list (also termed as Bill of Materials, "BoM", in engineering jargon) is an essential document for those who want to replicate your product. This document will help them understand which parts they have to get or make before assembling your product. The [http://www.iso.org/iso/iso_catalogue/catalogue_tc/catalogue_detail.htm?csnumber=43883 ISO 7573] provides a list of "minimum requirements for parts lists" and may help you setting up your BoM. If you are unable to access to this norm, here is information you can add to your BoM to describe each part of your product.
 
* '''Name of the part''': a short denomination allowing to quickly identify its function.
 
* '''Quantity''': that is, how many parts are necessary. You may also indicate if some extra parts should be bought as a precaution measure, in case the assembly of your product may go wrong.
 
* '''Exact specifications''': these are precise descriptions of the characteristics the part will have to fulfill, including the metrics and the units of measure, preferably in SI units. These descriptions are particularly important for parts like bolts, nuts and wires (see examples hereafter). Vague descriptions may not allow people who want to replicate your product to find suitable parts, which may be critical for the functionality of the end product. A good example of BoM containing sufficient specifications is given by the 3D printer [https://data.emotion-tech.com/ftp/%c2%b5Delta/Documentation/en/Old/%c2%b5Delta_rev1.0%20-%20Assembly-%c2%b5delta.pdf µdelta] and in illustration 2. A bad example for a part list would be just to say "you will need 20 small bolts, 10 large ones, a good battery and a long wire". With this information, the builders would not be able to find what they need. Here some examples of unambiguous specifications you can give:
 
**Bolts: diameter, length, kind of thread. For example, "M3x20" labels a metric screw thread with 3 millimeters diameter and 20 millimeters length.
 
**Nuts: norm, diameter, height. As an example, a nut [http://www.iso.org/iso/home/store/catalogue_ics/catalogue_detail_ics.htm?csnumber=26382 ISO 4032 M4] would be a hexagon nut with 3.2 mm height and 7 mm diameter.
 
**Battery: Type, voltage, typical capacity in mAh, technology. For example: LR6, 1.5 V, 2 850 mAh, alkaline.
 
* '''Procurement information''': that is, where the parts can be ordered. A list with possible suppliers will help makers of your product saving time. In the best case, you can recommend a supplier by providing a direct link to the part on the supplier`s website.  Also, stating an alternative procurement option can make sense. This might especially be considered as an option if you decide to recommend an online market place as a supplier. Because online market places only operate as mediators between retailers and customers, they do not ensure that the products are always available. As a result, products might be sold out without you noticing this, so an alternative procurement option can be helpful.
 
* '''Reference designation''': This is a reference code linking the part list and your technical documentation. With this code, the builder will know which component refers to which CAD file. This helps preserve the clarity of your documentation and makes the assembly easier. A good example for both procurement information and reference designation can be seen using the example of the laser cutter [https://www.lasersaur.com/manual/boms/bom-1403-suppliers-eur Lasersaur] (illustration 1). Not only is the part list arranged by suppliers and all the links to the components are provided, but builders can also directly see which subsystem of the final product the part belongs to. Alternatively, you could arrange the parts by module of the product they belong to, as this will simplify assembly later.
 
[[File:Lasersaur BoM.png|thumb|'''Illustration 1''': Bill of materials of the laser cutter [https://www.lasersaur.com/manual/boms/bom-1403-suppliers-eur ''Lasersaur''], edited]]
 
* '''Photo or illustration''': Putting a photo next to the textual reference of each part will help getting a quick overview of your part list. This will allow someone to search more efficiently for parts in the part list. A good example for providing photos can be seen in the parts list of the 3D-printer [https://data.emotion-tech.com/ftp/%c2%b5Delta/Documentation/en/Old/%c2%b5Delta_rev1.0%20-%20Assembly-%c2%b5delta.pdf µdelta] or in illustration 2.
 
* '''Prices''': it may be of interest to know the price of each part and the total procurement costs of the product. This can be ensured by stating the prices on the bill of materials or via the supplier homepage, in case the link is provided. Also, a rough estimation of total costs may be given. On the BoM of [http://www.lasersaur.com/manual/boms/bom-1403-suppliers-eur Lasersaur] (illustration 1), the prices of the single components and the added costs are provided.
 
There are different ways to present your Bill of Materials, but it is recommended to use a spreadsheet or a structured list. You want to make it as easy as possible for the builder to go through the list and procure all parts. If there is no explicit part list published, but the needed parts have to be extracted from the assembly instructions, the builders have to create their own "shopping list", which means unnecessary work for them. The following part list is an example of an unclear overview:"For your solar-powered generator, you will need six small hinges, five L-aluminum profiles with a length of about 5 meters each. For the solar box, you will need four aluminum profiles that are about 7 meters long and squared. Furthermore, you should buy 14 M6 bolts. You will also need a gel battery with 12 V and 10 meters of flexible cables." Not only is this part list vague, it also lacks important information in terms of metrics and it could be made a lot easier for the builder to provide information about where to procure the parts and how much they will cost. A better way for a BoM can be seen in illustration 2, which is an extract, based on the part lists of the solar-powered generator [http://www.instructables.com/id/Pop-up-Solar-Generator-SunZilla-30/step2/What-youll-need/ Sunzilla].
 
  
 +
 +
* '''Name of the part''': a short denomination allowing to quickly identifying its function.
 +
* '''Reference designation''': This is a unique reference code linking the parts list and your technical documentation. With this code, the maker will know which component refers to which CAD file. Reference designation and name of the part may eventually be the same, as long as the reference designation is unique and unambiguous.
 +
[[File:Lasersaur BoM.png|thumb|'''Illustration 1''': Bill of materials of the laser cutter [https://www.lasersaur.com/manual/boms/bom-1403-suppliers-eur ''Lasersaur''], edited]] 
 +
* '''Photo or illustration''': Putting a photo next to the textual reference of each part will help getting a quick overview of your parts list. This will allow someone to search more efficiently for parts in the parts list.
 +
* '''Exact specifications''': these are precise descriptions of the characteristics the part will have to fulfil, including the metrics and the units of measure, preferably in SI units. Avoid vague descriptions such as "you will need 20 small bolts, 10 large ones, a good battery and a long wire". This information may be insufficient to find the appropriate components and to reliably reproduce the functionality of your product. Here some examples of unambiguous specifications you can give:
 +
** Bolts: diameter, length, kind of thread. For example, "M3x20" labels a metric screw thread with 3 millimetres diameter and 20 millimetres length.
 +
** Nuts: standard, diameter, height. As an example, an [http://www.iso.org/iso/home/store/catalogue_ics/catalogue_detail_ics.htm?csnumber=26382 ISO 4032:1999] M4 nut would be a hexagon nut with 3.2 mm height and 7 mm diameter.
 +
** Battery: Type, voltage, typical capacity in mAh, technology. For example: LR6, 1.5 V, 2 850 mAh, alkaline.
 +
* '''Quantity''': that is, how many of such parts are necessary. You may also indicate whether some extra parts should be bought as a precautionary measure, in case the assembly of your product goes wrong.
 +
* '''Procurement information''': that is, where the parts can be ordered. A list with possible suppliers will help makers of your product to save time. In the best case, you can recommend a supplier by providing a direct URL hyperlink to the part on the supplier’s website. Stating an alternative procurement option can make sense as well.
 +
* '''Cost''': it may be of interest to know the cost of each part in order to calculate the total procurement costs of the product. You can either provide estimates or alternatively make references to market prices and provide URL hyperlinks to one or more suppliers.
 +
In illustrations 1, 2 and 3 you can see a few best practice examples, based on the parts list of [http://www.instructables.com/id/Pop-up-Solar-Generator-SunZilla-30/step2/What-youll-need/ Sunzilla] and [http://www.lasersaur.com/manual/boms/bom-1403-suppliers-eur Lasersaur], another good example is provided by [https://data.emotion-tech.com/ftp/%c2%b5Delta/Documentation/en/Old/%c2%b5Delta_rev1.0%20-%20Assembly-%c2%b5delta.pdf µdelta].
 
[[File:BoM.png|thumb|'''Illustration 2''': Edited extract from bill of materials of [http://www.instructables.com/id/Pop-up-Solar-Generator-SunZilla-30/step2/What-youll-need/ ''Sunzilla''],  
 
[[File:BoM.png|thumb|'''Illustration 2''': Edited extract from bill of materials of [http://www.instructables.com/id/Pop-up-Solar-Generator-SunZilla-30/step2/What-youll-need/ ''Sunzilla''],  
 
Pictures: [http://web.tradekorea.com/upload_file2/sell/57/S00010557/Stainless_steel_door_hinge_.jpg], [http://3d-alu.de/Aluminium_L-Winkel-Profil_50x20x2mm], [http://www.misumi-europe.com/en/e-catalog/vona2/detail/110302686450/?SYCD=CAF6-3030&PNSearch=CAF6-3030&searchFlow=results2products], [http://www.ostoase.de/SK-Schraube-M6x50?gclid=CJGi5bSW2s0CFQaNGwodrm4J0g], [http://uk.farnell.com/yuasa/np38-12/battery-12v-38ah/dp/145409], [http://www.batt.co.uk/products/view/701/Type-4C-Cable-600/1000V-BS6195]]]
 
Pictures: [http://web.tradekorea.com/upload_file2/sell/57/S00010557/Stainless_steel_door_hinge_.jpg], [http://3d-alu.de/Aluminium_L-Winkel-Profil_50x20x2mm], [http://www.misumi-europe.com/en/e-catalog/vona2/detail/110302686450/?SYCD=CAF6-3030&PNSearch=CAF6-3030&searchFlow=results2products], [http://www.ostoase.de/SK-Schraube-M6x50?gclid=CJGi5bSW2s0CFQaNGwodrm4J0g], [http://uk.farnell.com/yuasa/np38-12/battery-12v-38ah/dp/145409], [http://www.batt.co.uk/products/view/701/Type-4C-Cable-600/1000V-BS6195]]]
  
===Assembly Instructions===
+
===Share assembly instructions===
Once builders know which parts they need and how to procure them, they may require guidance for assembling your product. The European norm [http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=55833 EN 82079] may provide some guidance here. It defines the creation, structuring and presentation of technical manuals in terms of comprehensibleness, content, structure, appearance, design and language. More generally there are two main components for clear and understandable assembly instructions: text and illustrations. Both are described in detail below.
+
Once makers know which parts they need and how to procure them, they may require guidance to assemble your product. The international standard [http://www.iso.org/iso/home/store/catalogue_tc/catalogue_detail.htm?csnumber=55833 IEC 82079-1:2012] provides some guidance in that regard. It defines the creation, structuring and presentation of technical manuals in terms of comprehensibility, content, structure, appearance, design and language. Yet again, this document is not open source and not everybody can access to it. Here is some advice about the two main components of clear and understandable assembly instructions: text and illustrations.  
 +
 
 +
'''Text'''
 +
 
 +
A good instructional text finds the balance between richness of details and clarity. It should be detailed enough and mistake-proof, but not filled with unnecessary information that could lead to confusion. Concise language is essential if you want to reach a wide audience of readers, so you may want to minimize unnecessary technical jargon.
  
 
'''Illustrations'''
 
'''Illustrations'''
  
Illustrating assembly instructions makes them more clear and vivid. If you want to make it even easier for the builder, you can consider illustrating every assembly step. Varying the ways of illustrating the assembly steps may also be a good idea. Here are some possible ways of illustrating your assembly instructions:
+
Illustrating assembly instructions makes them more clear and vivid. There are at least two kinds of illustrations you can provide:  
* Photos: provide an easy way of illustrating the assembly steps and can be a means for the builders by which they can orientate themselves, as they can copy what they see without reading over the written instructions again and again.  
+
* ''Images'' provide an easy way of illustrating assembly steps. They help makers to quickly identify what is to be done and allow them to proceed per imitation. Images can either be photos of assembly steps or drawings such as CAD models. Even better is to annotate images with text and symbols. For example, an arrow can depict the path along which a part has to be moved in an assembly step.
* Illustrations or CAD-views: especially for 3D-printed parts, these can ensure clarity about the part that has to be printed.
+
* ''Videos or animated GIFs'' may be more powerful in their significance than photos, since they carry more information. In cases of very complex assembly steps, videos or GIFs might better express instructions that are difficult to formalize with text and static images.  
* Videos or GIFs: in case the assembly step is too complex to show it with pictures or ensuring clarity would require too many photos or illustrations, videos of GIFs might help.
+
Here and in illustration 3 are a few best practice examples you can look up: [https://github.com/Ultimaker/Ultimaker2/blob/master/um2%20assembly%20manual%20V1.1%20_english.pdf Ultimaker], [http://preciousplastic.com/en/videos/build/extrusion/ Precious Plastic].  
An example for one assembly step of the 3D printer [https://github.com/Ultimaker/Ultimaker2/blob/master/um2%20assembly%20manual%20V1.1%20_english.pdf Ultimaker], illustrated with photos, can be seen in illustration 3.
 
 
 
 
[[File:Assembly instructions.png|thumb|'''Illustration 3''': Assembly instructions of the 3D printer [https://github.com/Ultimaker/Ultimaker2/blob/master/um2%20assembly%20manual%20V1.1%20_english.pdf  ''Ultimaker'']]]
 
[[File:Assembly instructions.png|thumb|'''Illustration 3''': Assembly instructions of the 3D printer [https://github.com/Ultimaker/Ultimaker2/blob/master/um2%20assembly%20manual%20V1.1%20_english.pdf  ''Ultimaker'']]]
 
An example of both videos and 3D-views can be seen on the assembly instructions of [http://preciousplastic.com/en/videos/build/extrusion/ Precious Plastic].
 
 
'''Text'''
 
 
A good text finds the balance between richness of details and clarity. First of all, the steps should be clearly definite from each other in order to provide a clear structure. Also, the text should be detailed enough to be mistake-proof, but not filled with unnecessary information that can lead to confusion.
 
  
 
==Enable others to contribute to your design==
 
==Enable others to contribute to your design==
If you want to profit from collective intelligence and build a community actively participating in your product development project, there are at least three things you may consider: sharing editable information, publishing a contributing guide and supporting community interaction.
+
If you want to profit from collective intelligence to improve your product and build a community that actively participates in your product development project, there are at least two things you may consider: sharing editable information and publishing a contributing guide.  
 
===Share editable information===
 
===Share editable information===
Publishing non-editable files represents a barrier to potential contributions. For example, if you publish your CAD files in export formats like PDF or STL, your community members won’t be able to modify your design and contribute back to your project. On the contrary, sharing CAD files in their original processing format would facilitate the emergence of collective intelligence. This is also true for other kinds of information and files, for example product specifications, user manuals, bill of materials or assembly instructions.  
+
Publishing non-editable files represents a barrier to potential contributions. Sharing export CAD formats like PDF or STL may enable your community to study your design. Yet, those formats are hardly editable and they may not bear all information you had in your original CAD format (e.g. parameters and constraints). In contrast, sharing CAD files in their original processing format would allow others to access the entire information, to modify it and to make modifications.  
You may share editable information in two ways:
+
This is not only true for CAD drawings, but also for other kinds of information and files such as product specifications, user manuals, BOMs or assembly instructions.  
* Share information through editable files your community members can download.
+
There are at least two ways you can share editable information:  
* Share information through a Web 2.0 environment allowing online edition from your community members (e.g. a wiki).
+
* through editable files your community members can download/upload.
 
+
* through a Web 2.0 environment allowing online edition (e.g. a wiki).
 
===Publish a contribution guide===
 
===Publish a contribution guide===
If you want to build a community of co-designers, you may need to tell your potential contributors that they are welcomed to join the party. Publishing a contribution guide may be a good idea for this. Below, are some ideas for a motivating contribution guide.
+
If you want to build a community of co-designers, you may communicate publicly (i.e. make an open call) that interested persons are highly welcome to join and contribute in the product development. Publishing a contribution guide may be a good idea for this. Below are some advices for creating a motivational contribution guide.
 
+
State explicitly that people are welcomed and explain them ''what'' they can do. For example:  
State explicitly that people are welcomed and explain them ''what'' they can do. For example:
+
* take on already identified tasks/issues;
* Hand-in improvement suggestions;
+
* define new tasks/issues, for example by giving improvement suggestions or reporting bugs;
* Test the product and report bugs;
+
* contribute to the documentation regarding product assembly or usage;
* Contribute to the documentation regarding product assembly or use;
+
* help expressing product requirements;
* Leave comments;
+
* leave comments;
* Support your project financially.
+
* support your project financially.
After letting potential contributors know ''what'' they can do, you may want to explain them ''how'' they can contribute. For example  
+
After letting potential contributors know ''what'' they can do, you may want to explain them how they can contribute. For example by providing them practical information with regard to the following:
*Regarding your collaborative design tools:
+
* Collaborative design tools:  
**Where can the contributors find the files they need?  
+
** Where can the contributors find the files they need?  
**Which tools should the contributors use for which task?
+
** Which tools should they use?
**How can contributors register?  
+
** How can they register?
**How can they let others know what part of the project they are working on?
+
** How can they let others know what part of the project they are working on?
*Regarding information sharing and editing:
+
* The design process:  
**How can contributors share their designs?
+
** How can contributors make or suggest modifications?
**How can they add or edit information, designs or similar?
+
** How are contributions evaluated and integrated?
*Regarding your design rationale:
+
** What rules and guidelines should be followed when contributing to the project?
**Why is your product the way it is?  
+
* The design rationale:  
**Why you made the specific choices you did.
+
** Why is your product the way it is?  
*Regarding rules and guidelines:
+
** Why you made the specific choices you did.
**What rules and guidelines should the user follow when contributing to the project? In the best case, exact guidelines and / or policies for contributing towards the project can be given. These can be rules of what to write or not to write in the wiki, but also explicit guidelines of how to write a good wiki contribution or instructions for people interested in coding the software.
+
* The team
 
+
** Who is involved in the project and how?
Finally, you may want to explain potential contributors ''why'' they should contribute, that is, what can motivate them spending time and expertise in the project. Here are some elements that can help you with this:
+
** Which skills are currently needed in your project?
*Tell them what your vision is. It might be helpful to make it clear where you are heading with your project and what you want to change.  
+
Finally, you may want to explain potential contributors ''why'' they should contribute, that is, what can motivate them spending time and expertise in the project. Here are some elements that can help you with this:  
*People may be motivated by fun, the desire to learn new skills, or to create a better product, social aspects, networking, career development and even competition or rewards. You could make use of this and tell your potential contributors the benefits they can expect from contributing. For example:
+
* Tell them what your vision is. It might be helpful to make it clear where you are heading with your project and what you want to change.  
**You could explain the fields in which they can improve their skills and gain additional knowledge.
+
* People may be motivated by fun, the desire to learn new skills or to create a better product, social aspects, networking, career development and even competition or rewards. You could make use of this and tell your potential contributors the benefits they can expect from contributing. For example:  
**You could emphasize the fun factor of contributing to your project by explaining/showing the fun that you have and that other can expect.
+
** You could explain the fields in which they can improve their skills and gain additional knowledge.
**A sense of community motivates people participating in a co-creation task. You might want to emphasize the aspects of community building around your project.
+
** You could emphasize the fun factor of contributing to your project by explaining/showing the fun that you are having and that they can expect.
 +
** A sense of community motivates people participating in a co-creation environment. You might want to emphasize the aspects of community building and the collective spirit in your project.
 +
==General advice==
 +
''Showcasing helps''. You may share information helping others to understand your product and its functions. You may show renderings or previews of your product (an image of a 3D model or a photo of one of your prototypes) and concisely explain what it is about and which requirements it will meet.
  
==In all cases==
+
''Be clear about the products requirements.'' It may be interesting for others to understand not only the solution you are providing but also the problem you are solving. By doing so, you may explicitly state the initial problem or motivation behind your project so people understand clearly what you are trying to achieve.  
* Showcasing helps: you may share information helping others to understand your product and its functions. Show renderings or previews of your product (an image of a 3D model or a photo of one of your prototypes) and concisely explain what it is about and why it is needed.
 
* Requirements: it may be interesting for others to understand not only the solution you are providing but also the problem you are solving. Explicitly state the initial problem or motivation behind your project so people understand clearly what you are trying to achieve.
 
* Make information and documents easy to find. An intuitively and easy-to-use designed homepage helps a lot.
 
  
==What you must do so you can call your product "open source"==
+
''Make information and documents easy to find.'' An intuitively and easy-to-use designed homepage helps a lot. The necessity to fill a form in order to get the documentation may be interpreted as a violation of the principle of non-discrimination against persons or groups contained in the open source definition.  
To date, existing definitions of open source hardware do not draw a clear line between which piece of hardware can be qualified as open source and which do not. There are no official requirements that need to be fulfilled in order to call your project "open source".
 
However, a general rule of thumb is that the least you should do is to share the design files in original formats (see section "enable others to study your product") for all parts that you are designing by yourself.
 
In order to bring some clarity in this issue, the OSHWA is planning on introducing a certification of open projects. Users will be able to [http://www.oshwa.org/2015/09/19/open-source-hardware-certification-version-1/  self-certify the compliance of their project with the requirements of the OSHWA] and, in case of compliance, use their logo. There is no detailed information about the certification criteria available yet, however, the focus of the OSHWA is that everyone should <nowiki>“do the best they can”</nowiki> in terms of openness.
 
  
See also the page [[Open-O-meter]] for a more extensive discussion of this issue.
+
==Checklist: how open is your hardware?==
 +
The Open Source Hardware Association offers a certification programme allowing developers to self-certify the compliance of their product with the [http://certificate.oshwa.org/ open source hardware definition] . The clarity of this certification scheme is however restrained by the limited precision of the open source hardware definition highlighted in the introduction of the present document. It also considers openness as a binary criterion: either a product is open and can be certified (in accordance with compliance to defined threshold standards), or it is not. However, the different forms and levels of openness are not taken into account.
 +
In order to help you determine how open your product is, we introduce the concept of the [[Open-O-meter]]. See also the associated [[Open-O-meter | page]] for a more extensive discussion of this issue.

Revision as of 18:20, 16 February 2017

Note

The latest version of this document can be found on GitHub, open for collaboration and improvement. It can also be accessed via DepositOnce.

Practical advice for sharing product-related documentation

What makes a software program “open source” is that its source code is publicly available. What is pretty clear for software is less clear for hardware—especially for mechanical hardware. What does the term "source" refer to in "open source hardware"? According to the Open Source Hardware Association (OSHWA): "Open source hardware is hardware whose design is made publicly available so that anyone can study, modify, distribute, make, and sell the design or hardware based on that design." What does it mean to "make a design publicly available"? What are the documents that enable others to study, distribute, make or sell a design? This short guide provides practical answers to these questions and is dedicated to those who want to make a piece of mechanical hardware open source.

Preamble

The above cited definition implies four degrees of freedoms regarding a considered piece of hardware:

  • Freedom to study: i.e. the right to access enough information to understand how the piece of hardware (referred herein as the product) works and to retrace the logic behind its design;
  • Freedom to modify: i.e. the right to edit the product definition documents and to tweak or develop the product further for any purpose;
  • Freedom to make: i.e. the right to use the product definition documents to manufacture the piece of hardware;
  • Freedom to distribute: i.e. the right to share or sell the product definition documents as well as the physical products fabricated according to these documents.

A precondition for the realization of these degrees of freedom is that hardware must be released with its “source code”, which is termed in the referred definition as “documentation” or “design files”. However, what information has to be shared in order to allow any interested person to study, modify, make and distribute a piece of mechanical hardware—in other words, what is the source of open source mechanical hardware—is a question that is not trivial and remains unanswered in this definition. While sharing a CAD file would allow anyone to study the product design, this may be insufficient information to manufacture it. While sharing fully defined and detailed assembly instructions would allow anyone with sufficient production means and knowhow to manufacture the product, this may be insufficient to allow them to participate in the further design of the product. Is a product open source as soon as enough documentation is provided to ensure one of these freedoms? Or is it mandatory to provide enough documentation so that all of these freedoms are ensured? Is it enough to publish CAD files or is it mandatory to equally share assembly instructions? In the absence of clear answers to these questions, this guide strives to provide practical advice on information you may want to share with your community in order to make your piece of mechanical hardware open source. It shows what you can do, but does not pretend telling what you must do. It is based on the practical assumption that the type of information you may want to share depends on your motivation to go open source:

  • Is your motivation to demonstrate your customers how good your product is designed? Then put particular emphasis on publishing detailed and commented design files. See section “enable others to study your product”.
  • Do you want your innovative product to be manufactured by others so it can be rapidly adopted worldwide? Then put particular emphasis on publishing clear assembly instructions and a parts list. See section “enable others to make your product”.
  • Do you want to use open source as a means to improve your product by receiving feedback from others to or by even letting them take part in your product development project? Then put particular emphasis on publishing documents others can edit and tell potential contributors what you expect from them. See section “enable others to contribute to your design”.

Note that the maturity of your product also influences the content and the level of detail of your product documentation. If you are still at an early design phase, you may have only some description of the product concept and requirements in the form of sketches and text. If your product is fully defined, you may have complete CAD drawings and a stable parts list. But independent from the maturity of your design, the general rule of thumb is to share the information you have at the time you have it. In the following, the possible components of making your product open source are presented. This document is to be considered as complementary to the best practices of open source hardware published by the Open Source Hardware Association .

Enable others to study your product

If your motivation for going open source is to allow others to study your product, then you may want to publish your design files, i.e. the files you created to define your product. Design files are for example 2D drawings or 3D models, circuit board layouts, schematics or additional technical drawings that show the structure of your product in detail. Sharing these files will allow others to understand how your product is designed. In the best case, you will share your design files in their original format, that is, in the format in which you created them. Even better is to use free and open-source software applications and open file formats so that others do not have to buy expensive licenses to access the information you are sharing with them. Alternatively, you can share your design files in export file formats such as STL, PDF or PNG. Exporting your original files in those formats will however inevitably lead to loss of information. Therefore, sharing these files shall only be considered as additional measure, for example in cases you are using costly software that others may not be able to afford.

In any case you may:

  • share these files in a design repository to allow others to browse your files online (e.g. GitHub);
  • give the possibility to download packaged files in one click;
  • clearly separate original design files and exports by labelling them accordingly.

Enable others to replicate your product

If you want others to replicate your product, you may publish a parts list and assembly instructions. Below, you will find some recommendations regarding these two elements.

Share a parts list

A well-made and clear parts list (also termed as bill of materials [BOM] in engineering jargon) is an essential document for those who want to replicate your product. This document will help them understand which parts they have to source or manufacture before assembling your product. The ISO 7573:2008 standard provides a list of "minimum requirements for parts lists" and may help you with setting up your BOM properly. Unfortunately this document is not open source and not everybody can access it freely. Here is some advice about how to structure your BOM. A BOM may contain the following information for each part/component of your product:


  • Name of the part: a short denomination allowing to quickly identifying its function.
  • Reference designation: This is a unique reference code linking the parts list and your technical documentation. With this code, the maker will know which component refers to which CAD file. Reference designation and name of the part may eventually be the same, as long as the reference designation is unique and unambiguous.
Illustration 1: Bill of materials of the laser cutter Lasersaur, edited
  • Photo or illustration: Putting a photo next to the textual reference of each part will help getting a quick overview of your parts list. This will allow someone to search more efficiently for parts in the parts list.
  • Exact specifications: these are precise descriptions of the characteristics the part will have to fulfil, including the metrics and the units of measure, preferably in SI units. Avoid vague descriptions such as "you will need 20 small bolts, 10 large ones, a good battery and a long wire". This information may be insufficient to find the appropriate components and to reliably reproduce the functionality of your product. Here some examples of unambiguous specifications you can give:
    • Bolts: diameter, length, kind of thread. For example, "M3x20" labels a metric screw thread with 3 millimetres diameter and 20 millimetres length.
    • Nuts: standard, diameter, height. As an example, an ISO 4032:1999 M4 nut would be a hexagon nut with 3.2 mm height and 7 mm diameter.
    • Battery: Type, voltage, typical capacity in mAh, technology. For example: LR6, 1.5 V, 2 850 mAh, alkaline.
  • Quantity: that is, how many of such parts are necessary. You may also indicate whether some extra parts should be bought as a precautionary measure, in case the assembly of your product goes wrong.
  • Procurement information: that is, where the parts can be ordered. A list with possible suppliers will help makers of your product to save time. In the best case, you can recommend a supplier by providing a direct URL hyperlink to the part on the supplier’s website. Stating an alternative procurement option can make sense as well.
  • Cost: it may be of interest to know the cost of each part in order to calculate the total procurement costs of the product. You can either provide estimates or alternatively make references to market prices and provide URL hyperlinks to one or more suppliers.

In illustrations 1, 2 and 3 you can see a few best practice examples, based on the parts list of Sunzilla and Lasersaur, another good example is provided by µdelta.

Illustration 2: Edited extract from bill of materials of Sunzilla, Pictures: [1], [2], [3], [4], [5], [6]

Share assembly instructions

Once makers know which parts they need and how to procure them, they may require guidance to assemble your product. The international standard IEC 82079-1:2012 provides some guidance in that regard. It defines the creation, structuring and presentation of technical manuals in terms of comprehensibility, content, structure, appearance, design and language. Yet again, this document is not open source and not everybody can access to it. Here is some advice about the two main components of clear and understandable assembly instructions: text and illustrations.

Text

A good instructional text finds the balance between richness of details and clarity. It should be detailed enough and mistake-proof, but not filled with unnecessary information that could lead to confusion. Concise language is essential if you want to reach a wide audience of readers, so you may want to minimize unnecessary technical jargon.

Illustrations

Illustrating assembly instructions makes them more clear and vivid. There are at least two kinds of illustrations you can provide:

  • Images provide an easy way of illustrating assembly steps. They help makers to quickly identify what is to be done and allow them to proceed per imitation. Images can either be photos of assembly steps or drawings such as CAD models. Even better is to annotate images with text and symbols. For example, an arrow can depict the path along which a part has to be moved in an assembly step.
  • Videos or animated GIFs may be more powerful in their significance than photos, since they carry more information. In cases of very complex assembly steps, videos or GIFs might better express instructions that are difficult to formalize with text and static images.

Here and in illustration 3 are a few best practice examples you can look up: Ultimaker, Precious Plastic.

Illustration 3: Assembly instructions of the 3D printer Ultimaker

Enable others to contribute to your design

If you want to profit from collective intelligence to improve your product and build a community that actively participates in your product development project, there are at least two things you may consider: sharing editable information and publishing a contributing guide.

Share editable information

Publishing non-editable files represents a barrier to potential contributions. Sharing export CAD formats like PDF or STL may enable your community to study your design. Yet, those formats are hardly editable and they may not bear all information you had in your original CAD format (e.g. parameters and constraints). In contrast, sharing CAD files in their original processing format would allow others to access the entire information, to modify it and to make modifications. This is not only true for CAD drawings, but also for other kinds of information and files such as product specifications, user manuals, BOMs or assembly instructions. There are at least two ways you can share editable information:

  • through editable files your community members can download/upload.
  • through a Web 2.0 environment allowing online edition (e.g. a wiki).

Publish a contribution guide

If you want to build a community of co-designers, you may communicate publicly (i.e. make an open call) that interested persons are highly welcome to join and contribute in the product development. Publishing a contribution guide may be a good idea for this. Below are some advices for creating a motivational contribution guide. State explicitly that people are welcomed and explain them what they can do. For example:

  • take on already identified tasks/issues;
  • define new tasks/issues, for example by giving improvement suggestions or reporting bugs;
  • contribute to the documentation regarding product assembly or usage;
  • help expressing product requirements;
  • leave comments;
  • support your project financially.

After letting potential contributors know what they can do, you may want to explain them how they can contribute. For example by providing them practical information with regard to the following:

  • Collaborative design tools:
    • Where can the contributors find the files they need?
    • Which tools should they use?
    • How can they register?
    • How can they let others know what part of the project they are working on?
  • The design process:
    • How can contributors make or suggest modifications?
    • How are contributions evaluated and integrated?
    • What rules and guidelines should be followed when contributing to the project?
  • The design rationale:
    • Why is your product the way it is?
    • Why you made the specific choices you did.
  • The team
    • Who is involved in the project and how?
    • Which skills are currently needed in your project?

Finally, you may want to explain potential contributors why they should contribute, that is, what can motivate them spending time and expertise in the project. Here are some elements that can help you with this:

  • Tell them what your vision is. It might be helpful to make it clear where you are heading with your project and what you want to change.
  • People may be motivated by fun, the desire to learn new skills or to create a better product, social aspects, networking, career development and even competition or rewards. You could make use of this and tell your potential contributors the benefits they can expect from contributing. For example:
    • You could explain the fields in which they can improve their skills and gain additional knowledge.
    • You could emphasize the fun factor of contributing to your project by explaining/showing the fun that you are having and that they can expect.
    • A sense of community motivates people participating in a co-creation environment. You might want to emphasize the aspects of community building and the collective spirit in your project.

General advice

Showcasing helps. You may share information helping others to understand your product and its functions. You may show renderings or previews of your product (an image of a 3D model or a photo of one of your prototypes) and concisely explain what it is about and which requirements it will meet.

Be clear about the products requirements. It may be interesting for others to understand not only the solution you are providing but also the problem you are solving. By doing so, you may explicitly state the initial problem or motivation behind your project so people understand clearly what you are trying to achieve.

Make information and documents easy to find. An intuitively and easy-to-use designed homepage helps a lot. The necessity to fill a form in order to get the documentation may be interpreted as a violation of the principle of non-discrimination against persons or groups contained in the open source definition.

Checklist: how open is your hardware?

The Open Source Hardware Association offers a certification programme allowing developers to self-certify the compliance of their product with the open source hardware definition . The clarity of this certification scheme is however restrained by the limited precision of the open source hardware definition highlighted in the introduction of the present document. It also considers openness as a binary criterion: either a product is open and can be certified (in accordance with compliance to defined threshold standards), or it is not. However, the different forms and levels of openness are not taken into account. In order to help you determine how open your product is, we introduce the concept of the Open-O-meter. See also the associated page for a more extensive discussion of this issue.