Hardware Podcasts

Ep. 32 - How to Write Documentation

Open Hardware Manufacturing Podcast · 8 Nov 2024 · 1h 15m

What this episode covers

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.

Most relevant to

companies scaling up

Topics

Mentioned

Companies
Winterbloom
Products
OpenPNP, Voron, Lumen
Tools
MkDocs, GitHub Pages, Zucchini
Also
Google Style Guide, Thea Flowers, Bill Hader

Related episodes from other shows

Other shows on the same ground, closest first.

  • The Electromaker Show · 1h 08m

    Documentation as Code: A chat with Alasdair Allan from Raspberry Pi

    Alasdair Allan, Head of Documentation at Raspberry Pi, explains the 'Documentation as Code' philosophy used for the RP2040 and Pico W, emphasizing narrative and accessibility. He discusses the challenges of documenting custom ASICs, the pricing strategy behind the $4 Pico, and the importance of bridging the gap between expert engineers and generalist makers. Allan also shares personal project ideas, including a Wi-Fi mesh cannon and a personal time zone clock, while critiquing the friction in modern smart home technology.

    Embedded firmwareMicrocontrollers & dev platforms
    6 chapters

  • Embedded.fm · 1h 03m

    288: You Got a Screen!

    Elecia White and Christopher White discuss the disconnect between academic embedded systems education and industry reality, noting that schools often fail to teach practical tools like version control, debugging, and cross-compilation. They argue that while broad theoretical knowledge is valuable, students need exposure to real-world workflows, such as using STM32 Nucleo boards and J-Tag debuggers, to bridge the gap. The hosts then provide a comprehensive guide to professional documentation, emphasizing that self-documenting code is a myth and detailing specific artifacts like product docs, schematics with block diagrams, software specs, and user manuals. They highlight tools like Balsamiq for UI wireframing and emphasize the importance of clear, future-proof documentation to aid maintenance and collaboration.

    Careers & educationEmbedded firmware
    9 chapters

  • IDology · 28m

    Technical documentation in industrial design - IDology #19

    Piotr Dalewski and Rafał Piłat of Mindsailors explain that technical documentation serves as a universal language between designers, manufacturers, and quality control, ensuring parts meet precise tolerances and standards. They argue that 3D models alone are insufficient for mass production because they cannot convey material properties, surface finishes, or assembly requirements, making detailed documentation essential for accurate quoting and avoiding costly errors. The guests highlight that neglecting this documentation often leads to flawed parts and disputes, as manufacturers may claim they met unspecified 'best effort' standards rather than defined engineering requirements.

    Design for manufacturing & NPIQuality & yield
    8 chapters

  • The Amp Hour · 1h 00m

    Documentation Is A Waste Of Time

    Dave Jones and Chris Gammell discuss the critical role of documentation in hardware engineering, contrasting the rigorous requirements of military contractors with the 'get it done' culture of startups where knowledge is often lost when key designers leave. They analyze the Foxconn acquisition of Sharp as a supply chain security move by a giant with excess cash, and review the Raspberry Pi 3's integration of Wi-Fi and Bluetooth into its processor. The conversation concludes with a critique of the 'Coolest Cooler' Kickstarter failure, highlighting how poor unit economics and fulfillment planning can lead to bankruptcy despite massive funding.

    Careers & educationCrowdfunding & preorders
    7 chapters

  • Embedded.fm · 58m

    176: Let's Go Light It Up

    Toni Klopfenstein, Quality Assurance Manager at SparkFun, discusses the company's evolution from a hobbyist parts supplier to an education-focused hardware provider. He details the challenges of open source hardware certification through OSHWA, the importance of comprehensive documentation for community adoption, and SparkFun's strategic shift toward supporting teachers and students in classrooms.

    Open-source hardwareDirect-to-consumer & e-commerce
    7 chapters

The summary, chapters and topics are generated from the episode’s audio by this directory, not written by Open Hardware Manufacturing Podcast. The episode itself belongs to its publisher.