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

by Sean Marquez

So, this talk is on…

Special Thanks to

SCaLE volunteer team

Before we get started, I’d like to commend SCaLE volunteer team for making conferences s.a., this possible

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 who why how where

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

Distributed manufacturing - useful when faced by supplychain vulnerabilities, s.a., in the event of a global pandemic Open source can yield a better product by virtue of subjecting it to more eyes; "Given enough eyeballs, all bugs are shallow" - Linus' Law

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
```

Works with modern version control systems (s.a., git) Using a distributed version control tool means docs & design files can be released together, as to not go out ouf sync Using a distributed version control tool also 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 a model-based approach to documentation can be leveraged to allow for machine-queryable documentation; which would enable stakeholder-specific views, s.a., documentation for regulatory audits

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

Regulatory bodies s.a., the FDA requires documented processes demonstrating manufactured medical devices are safe & effective as well as traceable audit trail of the design processes - which can be satisfied, using a docs-as-code approach, via doctools, linters, distributed version control system, & code review practices used in software development

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/

WTD is A community for technical writers & documentarians; You can join their online slack group; they also have a podcast (so if you’re stuck in LA traffic and looking for a new podcast; there you go)

Open Source Hardware Association

OSHWA

https://www.oshwa.org/

OSHWA is the organization that certifies OSHW projects; They also have a discord channel & (as of recently) an open-standards working group

Mach30 Foundation

Mach30

http://mach30.org/

Mach30 is a non-profit, originally chartered to develop Open Space Hardware; They specialized in model-based approaches to process and tooling development for OSHW

Tetra Bio Distributed

https://www.tetrabio.org/

Tetra is a non-profit, pioneering development of medical OSHW in collaboration with subject matter experts at USC

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/

oshw-standards project is led by the OSHWA working group to develop open standards s.a., for configuration management & quality management of OSHW for industries s.a., Medical & Aerospace DOF is a framework for distributed open-source hardware; think NodeJS/NPM’s package management for distributed OSHW QMS-CLI is a tool being developed by Tetra for generating/managing documentation for quality management of medical OSHW PAPRa is kind of Tetra’s flagship OSHW respirator project that is published using a docs-as-code approach This presentation is also published using a docs-as-code approach (so, if you’d like to contribute to improving this very presentation, open an issue!)

Let’s go build open-source hardware!

A Docs-as-Code approach to Medical/PPE Open-Source Hardwareby Sean Marquez So, this talk is on…