by Sean Marquez
So, this talk is on…
SCaLE volunteer team
Before we get started, I’d like to commend SCaLE volunteer team for making conferences s.a., this possible
-
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
-
Medical Devices or Personal Protective Equipment (PPE’s) developed as Open Source Hardware (OSHW)
-
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)
The philosophy/practice that documentation should be maintained using the same tools & approach as code
-
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
-
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
FDA Code of Federal Regulations Title 21 Part 820 - Quality System Regulation for Medical Devices
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
-
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)
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)
OSHWA is the organization that certifies OSHW projects; They also have a discord channel & (as of recently) an open-standards working group
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 is a non-profit, pioneering development of medical OSHW in collaboration with subject matter experts at USC
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!)