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

by Sean Marquez

Special Thanks to

SCaLE volunteer team

Outline

  • 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

Language

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

Toolchain

  • 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

Methodology

  • 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

WTD

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

Open Source Hardware Association

OSHWA

https://www.oshwa.org/

Mach30 Foundation

Mach30

http://mach30.org/

Tetra Bio Distributed

Tetra

https://www.tetrabio.org/

Contribute

Open Standards for OSHW

https://github.com/oshwa/oshw-standards

Distributed Open-Source Hardware Frameworks

https://github.com/Mach30/dof/

Tooling

https://github.com/tetrabiodistributed/qms-cli

PAPRa (open-source hardware respirator)

https://github.com/tetrabiodistributed/papra

This presentation!

https://github.com/tetrabiodistributed/docs-as-code-for-medical-oshw/

Let’s go build open-source hardware!