A Docs-as-Code approach to Medical/PPE Open-Source Hardware

by Sean Marquez

Special Thanks to

SCaLE volunteer team


  • Terms/Definitions

    What is a Medical Device or PPE as Open-Souce Hardware (OSHW)?
    What is a Docs-as-code approach?
  • Stakeholder Needs

    Why develop Medical Devices/PPE's as OSHW (using a Docs-as-Code approach)?
  • Methodology

    How to adopt a docs-as-code approach to Medical/PPE OSHW
  • Community Resources & Where to Contribute

What is Open Source Medical/PPE Hardware?

  • Medical Devices or Personal Protective Equipment (PPE’s) developed as Open Source Hardware (OSHW)

What is Open Source Hardware?

  • OSHW is hardware developed/published like Open Source Software (OSS)

    (source: OSHWA definition for OSHW)
  • License (s.a, CERN Open Hardware License) allows for modificatoin/redistribution of hardware design

    (source: OSHWA definition for OSHW)
  • Documentation & design tools themselves should be open-source

    (source: OSI definition for OSS)

What is Docs-as-Code?

The philosophy/practice that documentation should be maintained using the same tools & approach as code

Why develop Medical Devices/PPE’s as OSHW (using a Docs-as-Code approach)?

  • Distributed manufacturing useful when faced by supplychain vulnerabilities, s.a., in the event of a global pandemic

  • Quality product By leveraging talent of the open-source hardware developer community

Why use a Docs-as-Code approach?

  • Works with modern version control systems (s.a., git)

  • Allows for parallel development

  • Reviewing documentation is like a code review

  • Content can be open-sourced, allowing anyone to contribute

  • Doctools can be leveraged to produce stakeholder-specific documentation

    s.a., for quality management, /auditability

Regulatory Environment

21 CFR 820
FDA Code of Federal Regulations
Title 21 Part 820 -
Quality System Regulation
for Medical Devices
ISO 13485:2016
Medical Devices -
A Practical Guide -
Requirements for Regulatory Purposes

How to adopt a Docs-as-Code approach

  • Language

  • Toolchain

  • Methodology


Consider the following…​

  • Markup Language

    s.a., Markdown, RestructuredText, LaTeX, Asciidoc
  • Template Language

    s.a., Liquid, Jinja2, Handlebars
  • Modeling Language

    s.a., OML, SysML v2


  • Text Editor / IDE

    s.a., vim, nano, VS code
  • Version Control System

    s.a., git, svn, mercurial
  • Static Site Generator / Rendering Engine

    s.a., Sphinx, Asciidoctor, Hugo
  • Issue Tracker

    s.a., Jira, GitHub, GitLab
  • Publishing Platform

    s.a., GitHub Pages, ReadTheDocs, Netlify
  • Automation Pipeline

    s.a., GitHub Actions, Jenkins


  • Workflow

    s.a., Docs-Driven-Development: Write your docs first, then implement what you documented
  • Contributing guidelines

    s.a., style guide, code of conduct
  • Agile Development Practice

    e.g., scrum, kanban
  • Code (Docs) Review Process

    Have someone review your docs (e.g., as a pull request on GitHub)

Community Resources

Write The Docs


A community for technical writers & documentarians https://www.writethedocs.org/

Open Source Hardware Association

Mach30 Foundation

Tetra Bio Distributed


Open Standards for OSHW


Distributed Open-Source Hardware Frameworks




PAPRa (open-source hardware respirator)


This presentation!


Let’s go build open-source hardware!