# Documentation

---

### Gosh Forum Thread on tools: https://forum.openhardware.science/t/product-development-toolchain/2181/5

---

Who's in the session:

- Moe
- Andre
- Al Edwards
- Lionel
- Oliver
- Joel
- Julian
- Ed
- Kaspar
- Chas
- Felipe
- Toby
- Emilio
- Daniel

Moe: How to align good documentation systems that work for companies science

Al: wants to learn how to document open source hardware from people who've done it.

Julian:
### what is documentation in hardware?
- how to use
- assembly instructions
- How to repair

**Toby**: You want to make project findable and easy to replicate. All this projects that are proprietary are good for findability, but terrible when it comes with project documentation.

Thinking about documenting you ahve to think about the end user, who is this being written for?

**Lionel**: it is implied by this that this is for small projects, for larger and/or projects taht have special requirments, you need other things, like medical projects that you need more info, like discarding, and customer support, etc.

**Moe**: We try to tackle issues with the different levels of complexity/technology inside a project by a self-accessment system, where you can see what is needed for different types of projects.
- also what is the advantage of documenting things, beyond more people being able to reproduce it.

**Joel**: Standardized documentation can still be crappy documentation, as even though you may be able to tick all the boxes of the spec, you can still do a terrible job, eg bad drawings, explanations that are intended for experienced people.

**Al**: One could add a peer-rebuilding process to help with quality assessment(accessment?).

**Lionel**: I would like to disentangle building instructions and project documentation. Analogy between SW domain: code -> compiler -> machine instructions and HW domain: blueprints -> assembler -> device

**Felipe**: I've developed many different tools, but I don't hjave time to document then. There is no incentive to do so, ie if I document something for patenting, there is a clear incentive for it.

**Joel**: maybe we should just remove all benefits that come from publishing open source tools, unless they are properly document.

**Andre**:documentation should be a continous process and tools must support that

**Joel**: We could add a CI system to check additions of hardware to repositories.

**Lionel**: there could be more effort on...

**Al**: Academics have access to funding, so one application of the funding could be to get people hired to document projects (documentation engineers). Would that interesting?

**Joel**: Playing the devil's advocate, there is always an excuste not to write documentation, since it is boring, and we want to be in the lab building things.

**Andre**: documentation should be seen as something boring, but highly beneficial.

**Chas**: Documentation for hardware should include rational, why we decided to do things in a certain way. it is called a "Thesis", which makes it much easier further down the line to write up papers, actual thesis.

**Oliver**: I want teachers to use my devices, so I need to think about documentation for people who for instance have never soldered anything. So I would propose for people to think about documentation with a specific user in mind. Try finding at least one interested user and use that as a motivation to make the documentation good enough for at least that user.

**Daniel**: From a biologist perpective who is starting to get into this, I need/would like to know what parts in the design are doing, so that I can know what can be swapped or how important they are for the end product, remember that end users a lot of times don't have a engineering background

**Moe**:

**Ed**: We can spend a lot of time writing documentation, (as opposed to having no time to write it) and still be rubbish.

**Joel**: We had an outreach person build our device, and even if she was from a physics background, and she had 3 pages of comments!

**Kaspar**: I'm using tools available in the industry so that the documentation is not only understood by technical people. ASD-STE100 specification for simplified technical english looks interesting.

**Julian**: We've got stuck in assembly instructions, but we would like to move to talk about logs, user guides, certificates.

**Toby**: documenting possible new solutions, new ways of building the same tool (thinking about improvements for next iterations), is a good way to deal with logs, and versioning, so maybe other people can start from where you've stopped.

**Martin**: DIN standard for open source hardware and register (soon) on https://oho.wiki which will track review/re-building issues going further than OSWA certification

#### One deliverable for this session would be to come up with a list of documentation tools (eg dozuki, docubriks, wikifab, etc). We can do this by contributing to the Gosh forum thread on toolchain (link at top of document).

---