[DAY 1] Documentation of Open Science Hardware


#1

Note taker: Analia
Facilitator: Leonardo

Other participants: @mariafrangos, @Tobey, @biomurph, @JiLi, … (please add others).

Summary

The session addressed the main issues related to OSH documentation, challenges and best practices to include in this process. The discussion included different point, with mainly where related to what and when document, who should be taken into consideration as the audience of our documentation, which tools are available to be used on our documentation process and what are the next steps to be done. Documentation should be oriented to reuse values and the understanding what we are doing as values. In addition when documenting it should be taken into consideration other themes that are related to technical aspects of the projects but are not technical. We should included the details of the beginning of our project. There are already also tools that are available such as the Open Hardware Journal and OSH certified projects which are already available all together in a database. We conclude that documentation is a process that involves quality, time, context and best practices to be implemented.

Notes

Participant shared their interest and concerns about:

  1. Quality and time. Doing the documentation at the same time as you are working has a challenge in order to achieve good quality results.
  2. How to document all the process, both the visible and not visible actions.
  3. How do we enforce documentation
  4. Share the experience of certified open source
  5. How can we understand the different audience related to OH
  6. Learn from others experiences. Identify prior problems so as not to replicate them in future projects. Guidelines and best practices related to Osh

The discussion includes different aspects, below the main ideas that arised:

A. We can learn from prior experiences related to documentation from past Gosh. (Available in google docs) make the people have the habit to document from the very beginning. A way to do that would be to highlight the benefits.

B. Also another tool to find more about OSH is certification. We need as a community to find a way to project that has bee developed or solved by other. Certification makes available a list of projects. Could be a way or solution to implement a method to make projects available. Try to create a database or a system to find the data or the projects

C. Other tool is the Open Hardware Journal as a resource. It includes also topics such as policies, education, economics and law.

B. Documentation should be oriented to reuse values and the understanding what we are doing as values.

C. Take into consideration language barriers (too technical, less technical) Language and technical language barrier for the general public (step by step methods as a recipy could extend the interest into more people but also have a balance with the educational purposes where this method would not be the more suitable for its owns goals.

D. Document the whole process and experiences, failures and context related to it. Also When documenting take into consideration other themes that are related to technical aspects of the projects but are not technical. We should included the details of the beginning of our project.

E. Finally, as a prior step identify the audience before starting the documentation process., taking into consideration their technical level to understand the documents that we are going to produce

The actions that can be taken are related to 3 main tags:

I. Recover the past GOSH documentation document and move forward after this conversation.

II.Create a hub of information which could map all the projects, starting with gosh community

III. Go back to the idea of sharing rather to the idea of document which is not dynamic.


GOSH Mapathon? Or GOSH Big Picture? Or even who are we? (GitLab issue #100)
#2

I didn’t know how to add that in the format proposed for the report, but one of the thoughts raised during the session (yeah, it was me) was that we were thinking about some best practices but sometimes people don’t have any practice, people don’t document at all.

So I think one good way to follow this discussion is to try to understand the reason why people don’t document and how to develop a documentation culture, which would be an approach to solve the issue. Maybe we can start a different thread once it gets clearer.


#3

I wasn’t part of this session but I have thought about this quite a bit. Every time someone releases an open source hardware electronics project but doesn’t document it using the Kitspace tools I think about why.

The crux of it is: people are lazy/busy/have more important things to do. They are not incentivized towards documenting. At the moment when they are in the best position to document, when they have just finished their design, the first thing on their mind is “how do I get everything together to make this”.

So my plan for Kitspace is to make the documentation process the easiest path to buying/making everything. I think there is a general insight here that could work in other fields, especially when the project involves digital manufacturing or is largely an assembly of bought components.


#4

How do you do or plan to do that incentive in Kitspace?

In CTA, we normally orient collaborators from the first time they get into the lab to document each step and we show some technical solutions for that. Even so, normally takes a while until people start doing it regularly. We wait people to face difficulties of not documenting (like forgetting important details to follow the development) and then they start to feel the importance of it.

Thank you!
Salve!