# Ep. 32 - How to Write Documentation

- Show: [Open Hardware Manufacturing Podcast](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast)
- Published: 2024-11-08
- Length: 1h 15m
- Page: https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation
- Listen: https://opulo.io

## Summary

Steven Haus and Lucian Che Park of Opulo discuss the challenges and best practices of writing documentation for open hardware products. They advocate for a dynamic, living documentation approach using MkDocs and Markdown, emphasizing that photos are superior to text or CAD renders for assembly instructions. The hosts also cover the pitfalls of video documentation, the importance of user testing with non-technical individuals, and strategies for handling community feedback and internationalization.

## Chapters

- [0:01](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=1) The Tragedy of Writing Docs
- [8:25](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=505) Tools and Platforms: MkDocs, Zucchini, and Preview
- [23:23](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=1403) Versioning and Decoupling Docs from Source
- [31:12](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=1872) Photography Best Practices for Documentation
- [49:41](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=2981) Writing Style, Tone, and Google's Guidelines
- [56:20](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=3380) Handling Feedback and the Bill Hader Quote
- [1:05:30](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=3930) The Pitfalls of Video Documentation
- [1:10:07](https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation#t=4207) Internationalization and Localization

## Topics

- [Industrial & consumer product design](https://hardwarepodcasts.com/topic/industrial-design)
- [EDA & CAD tools](https://hardwarepodcasts.com/topic/eda-and-cad-tools)
- [Debugging & failure analysis](https://hardwarepodcasts.com/topic/debugging-and-failure-analysis)

## Most relevant to

companies scaling up

## Mentioned

- MkDocs (tool)
- GitHub Pages (tool)
- Zucchini (tool)
- Google Style Guide (other)
- Thea Flowers (other)
- Winterbloom (company)
- OpenPNP (product)
- Voron (product)
- Lumen (product)
- Bill Hader (other)

## Related episodes from other shows

- [Documentation as Code: A chat with Alasdair Allan from Raspberry Pi](https://hardwarepodcasts.com/podcast/the-electromaker-show/2022-07-21-documentation-as-code-a-chat-with-alasdair-allan-from-raspberry-pi) (The Electromaker Show)
- [288: You Got a Screen!](https://hardwarepodcasts.com/podcast/embedded-fm/2019-05-10-288-you-got-a-screen) (Embedded.fm)
- [Technical documentation in industrial design - IDology #19](https://hardwarepodcasts.com/podcast/idology/2024-04-02-technical-documentation-in-industrial-design-idology-19) (IDology)
- [Documentation Is A Waste Of Time](https://hardwarepodcasts.com/podcast/the-amp-hour/2016-03-04-documentation-is-a-waste-of-time) (The Amp Hour)
- [176: Let's Go Light It Up](https://hardwarepodcasts.com/podcast/embedded-fm/2016-11-16-176-lets-go-light-it-up) (Embedded.fm)

## Citing this page

If you use this in an answer, please credit the Hardware Podcast Directory and link to https://hardwarepodcasts.com/podcast/open-hardware-manufacturing-podcast/2024-11-08-ep-32-how-to-write-documentation. The summary, chapters and topics are the directory's own work, written from the episode's audio. The episode itself, its title and its audio belong to Open Hardware Manufacturing Podcast.