# Seminar week 2: Documentation of Open Hardware [Back to overview](https://hackmd.io/ya-g7omdSI--Vx0JcayB1Q?view) [Link to the lesson](https://hackmd.io/C1eJ3lmSQ7ijtGi0FtTcGg) ## Participants |initials| name | discord user | |------|-----|-----| |MM| Miguel Felipe Marrero Tarrau | |JU| Jose Carlos Urra Llanusa | jurra |SI|Santosh Ilamparuthi|Santosh |IS|Ivan Santana Ching| ischingx |OM|Omar Milián Morón| omilian93 |sr|Sara Reichert| sarara | |Andjela| |VK|Vincent Kranendonk|vincent_kranendonk |TH|Tom Hommes| |NA| Nemo Andrea | sandcrawler |AP| Alice Peck | Alicee |ME| Mohammad Ebrahimi | moeb8001| |MB| Mathijs van Binnendijk | Mat | |JO| Pepe Ocampo | jossoca | ## Icebreaker: When was the last time you read instructions? JU: a day ago, I bought a rat trap to catch a mouse in my flat SI: Got a new wireless headphone and didn't need to ready the instructions since it had a QR code which set up everything. Vincent: Yesterday, egg cooker, because I want to see if I can use the heating element Sara: innocampus tu Berlin how to get rooms for seminars Tom: This week for a Pure Data object, but for actually building something I can't even recall. Andjela: Usually I don't read any manual, and if I need, then I feel sad (: For me it is that tiny spark of happiness that I can make it just from my head. Just to confirm my neurological network is still working :D Mathijs: Yesterday, I have to read datasheets of ICs quite often Mohammad: This week. About Hackmd and Markdown. It was my first time using them and had no idea how to use them. Alice: same as Mohammad :) > Nemo: [Photoresist datasheet](https://www.microchemicals.com/micro/tds_az_5214e_photoresist.pdf), just today. Pepe: Built a commercial work bench for carpentry :) ## Exercise 1: Start sharing your documentation :::warning Add comments down here ::: ::: spoiler MM Vincent: https://github.com/studiorabota/hello-worm Mathijs: https://github.com/mathijsvb/multicopterfcs Introduction to the project: Data acquisition and transmission module for flowmeters https://hackmd.io/@M3VcsL8RSjmCZdMQNzeMwA/BydAAeaC9 ::: ::: spoiler IS https://hackmd.io/@GhvLX58BSe2jAdrjr4xb0g/ByJaqp209/edit ::: > NA: A while ago I designed a 3D printable dock for my laptop. I think the documentation for that is pretty decent for the project scope. [it is available on my github](https://github.com/NemoAndrea/HP-zbook-printable-dock) ::: spoiler OM Omar: https://hackmd.io/@5FqUxdbyQmWQY7rZTEcNWA/B1OqLZp0c ::: :::spoiler Mohammad Introduction: https://hackmd.io/@moeb8001/B1HlPk2C5 ::: :::spoiler Pepe Intro: https://github.com/jossoca/OHA_micro ::: ## Exercise 2: See how others do it :::warning Your notes here ::: Vincent: The way [candlesmarthome.io](https://www.candlesmarthome.com/) builds on a more technical documentation of [webthings.io ](https://webthings.io/docs/) is really nice. Making it more accessible. They also have a way of generating code based on the user preferences. ::: spoiler NA: Elektronika-1 A replacement module for a USSR made vintage LED watch I decided to pick the [ELEKTRONIKA-1 - A replacement module for a USSR made vintage LED watch anno 1978](https://github.com/BenjaminSoelberg/elektronika-1) project by Benjamin Soelberg. >Why? It seems to have some decent documentation, and it revitalises old hardware, which is a good challenge. 👍 Liked: * Pictures of the actual device * Some background about the original hardware * Good high level overview * Lists practical performance and limitations * Hardware motivation 👎 Could be improved: * Repository images could be in a subdirectory (it's messy now) * Software setup / microcontroller programming could be explained * `docs` directory seems to contain mostly background research material, should perhaps be somewhere else * Add a little video in action * In general not set up fully for reproduction (but given the niche nature of the project, that's understandable) But all in all, the project is all available if you are willing to take the time to sort through the files. Given how niche it is, it is a commendable effort. I have seen much much worse. ::: JU: Question? Is there an analogous thing in hardware documentation for software examples folder: - JU: I like the open builds concept of sharing not only the documentation but also the result of the actual build. To buy Openbuild components in Europe I used - https://ratrig.com ## Exercise 3: Make a plan for the future :::warning Your notes here ::: Vincent: Documentation time so far: 6 - 8 hours Would like to make videos, always forget. 1. Electronics version in combination with WebThings 2. Physical bin with 3D files 3. Electronics version in combination with phone app ::: spoiler Nemo: LED driver board documentation targets *This pertains to my LED driver PCB sculpture project. When the hardware is tested and finalised the documentation should contain* **Core** * landing page, little demo webp video preview, project at a glance * Component lists, and where to source them * Assembly instructions * Instructions on setting up the ESP-32 * Instructions on running a hardware check + the code to run that check * Warnings on power supply choices and usage * Explaination on the artwork/biology behind the item **Optional** * Comments on hardware choices (why this component, not another) * PCB walkthrough * Extendability guide (Rust code - e.g. flash lights upon email) ::: # Tools: - doxygen and a md grabber. - [Rust](https://www.rust-lang.org/) comes with [built-in documentation builder tool](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html), which automatically gets its own static online html page when you publish package ## What things you liked others have done? - Nemo animations and detailed images to guide x - Mathijs Roadmap X ## Feedback - How do you find the material not very useful: was it very long?: Very basic: Perfect: xxxxxx Very advanced: ### Other remarks: ### What topics or aspects were you expecting that we missed?