Docops/capture requirements with traceability/120

.gitignore

@@ -8,4 +8,16 @@ static/
 # asciidoctor
 .asciidoctor/
 *.svg
-.DS_Store
+.DS_Store
+
+# node modules
+node_modules/
+
+# bundler
+_build
+
+# build script generated files
+dist/
+
+# github action keys
+gh-pages*

.gitmodules

@@ -2,3 +2,6 @@
 [submodule "themes/docsy"]
 	path = themes/docsy
 	url = https://github.com/google/docsy
+[submodule "m30pm"]
+	path = m30pm
+	url = [email protected]:Mach30/m30mlTools.git

architecture/0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml

@@ -0,0 +1,2 @@
+title: Joint Statement on Multiple Patients Per Ventilator
+url: 'https://www.asahq.org/about-asa/newsroom/news-releases/2020/03/joint-statement-on-multiple-patients-per-ventilator'

architecture/1-StakeholderNeeds/01-VolumesFillMostCompliantLungSegment.yaml

@@ -0,0 +1,5 @@
+id: 1
+name: Volumes fill most compliant lung segment
+statement: Volumes would go to the most compliant lung segments
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/02-PEEPWouldBeImpossibleToManage.yaml

@@ -0,0 +1,5 @@
+id: 2
+name: PEEP would be impossible to manage
+statement: Positive end‐expiratory pressure (PEEP), which is of critical importance in these patients, would be impossible to manage.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/03-MonitoringPulmonaryMechanicsImpossible.yaml

@@ -0,0 +1,5 @@
+id: 3
+name: Monitoring pulmonary mechanics impossible
+statement: Monitoring patients and measuring pulmonary mechanics would be challenging, if not impossible.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/04-AlarmMonitoringNotFeasible.yaml

@@ -0,0 +1,5 @@
+id: 4
+name: Alarm monitoring infeasible
+statement: Alarm monitoring and management would not be feasible.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/05-IndividualizedManagementForClinicalImprovement.yaml

@@ -0,0 +1,5 @@
+id: 5
+name: Individualized management for clinical improvement
+statement: Individualized management for clinical improvement or deterioration would be impossible.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/06-StopVentilationInTheEventOfCardiacArrest.yaml

@@ -0,0 +1,5 @@
+id: 6
+name: Stop ventilation in the event of cardiac arrest
+statement: In the case of a cardiac arrest, ventilation to all patients would need to be stopped to allow the change to bag ventilation without aerosolizing the virus and exposing healthcare workers.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/07-AddedCircuitVolume.yaml

@@ -0,0 +1,5 @@
+id: 7
+name: Added circuit volume
+statement: The added circuit volume defeats the operational self‐test (the test fails).
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/08-ExternalMonitoringRequired.yaml

@@ -0,0 +1,5 @@
+id: 8
+name: External monitoring required
+statement: Additional external monitoring would be required. The ventilator monitors the average pressures and volumes.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/09-PatientsDeteriorateAndRecoverAtDifferentRates.yaml

@@ -0,0 +1,5 @@
+id: 9
+name: Patients deteriorate and recover at different rates.
+statement: Patients deteriorate and recover at different rates, and distribution of gas to each patient would be unequal and unmonitored.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/1-StakeholderNeeds/10-GreatestRisksWithSuddenDeterioration.yaml

@@ -0,0 +1,5 @@
+id: 10
+name: Greatest risk with sudden deterioration
+statement: The greatest risks occur with sudden deterioration of a single patient (e.g., pneumothorax, kinked endotracheal tube), with the balance of ventilation distributed to the other patients.
+derivedFrom:
+  - "0-References/1-JointStatementOnMultiplePatientsPerVentilator.yaml"

architecture/2-UserStories/1-VolumeAdjustment.yaml

@@ -0,0 +1,10 @@
+id: 1
+name: Volume Adjustment
+actor: Clinician 
+behavior: individually adjust valves
+rationale: control volumetric flowrate per patient
+derivedFrom:
+- "1-StakeholderNeeds/01-VolumesFillMostCompliantLungSegment.yaml"
+- "1-StakeholderNeeds/05-IndividualizedManagementForClinicalImprovement.yaml"
+- "1-StakeholderNeeds/09-PatientsDeteriorateAndRecoverAtDifferentRates.yaml"
+example: Adjusting flow for each patient, decreasing PIP for the healthier lungs, and increasing PIP for the less healthy patient.

architecture/2-UserStories/2-MatchingProtocols.yaml

@@ -0,0 +1,10 @@
+id: 2
+name: Matching Protocols
+actor: Clinician
+behavior: {activity-that-manages-matching-protocols}
+rationale: maintain matching protocols per patient volume
+derivedFrom:
+- "1-StakeholderNeeds/01-VolumesFillMostCompliantLungSegment.yaml"
+- "1-StakeholderNeeds/05-IndividualizedManagementForClinicalImprovement.yaml"
+- "1-StakeholderNeeds/09-PatientsDeteriorateAndRecoverAtDifferentRates.yaml"
+example: {example-here}

build.sh

@@ -1,5 +1,34 @@
 #!/usr/bin/env bash
 
+# Install node_modules, if not already installed
+if [ ! -r ./node_modules ]; then
+    docker run --rm --volume "$PWD:/src" -w "/src" capsulecorplab/asciidoctor-extended:asciidocsy-nodejs 'npm ci'
+fi
+
+# Install m30pm node_modules, if not already installed
+if [ ! -r ./m30pm/node_modules ]; then
+    docker run --rm --volume "$PWD:/src" -w "/src" capsulecorplab/asciidoctor-extended:asciidocsy-nodejs 'cd m30pm && npm ci'
+fi
+
+# Make dist/ directory, if none exists
+if [ ! -r ./dist ]; then
+    mkdir dist/
+fi
+
+# Build the unified model
+docker run --rm --volume "$PWD:/src" -w "/src" capsulecorplab/asciidoctor-extended:asciidocsy-nodejs 'node m30pm/buildUnifiedModel.js && cp dist/architecture.yaml dist/architecture.yml'
+
+# generate tetra-requirements.adoc from liquid template
+docker run --rm --volume "$PWD:/src" -w "/src" capsulecorplab/asciidoctor-extended:asciidocsy-nodejs 'node m30pm/generateDoc.js --unifiedModel=dist/architecture.yaml --template=templates/tetra-requirements.adoc.liquid --out=dist/tetra-requirements.adoc'
+
+# generate pdf-theme.yml from liquid template
+docker run --rm --volume "$PWD:/src" -w "/src" capsulecorplab/asciidoctor-extended:liquidoc 'bundle exec liquidoc -d dist/architecture.yml -t templates/pdf-theme.yml.liquid -o dist/pdf-theme.yml'
+#docker run --rm --volume "$PWD:/src" -w "/src" capsulecorplab/asciidoctor-extended:asciidocsy-nodejs 'bundle exec liquidoc -d dist/architecture.yml -t templates/pdf-theme.yml.liquid -o dist/pdf-theme.yml'
+
+# generate tetra-requirements.pdf
+docker run --rm --volume $PWD:/src -w "/src" capsulecorplab/asciidoctor-extended:asciidocsy-nodejs 'asciidoctor dist/tetra-requirements.adoc -o dist/tetra-requirements.pdf -r asciidoctor-pdf -r asciidoctor-diagram -b pdf -a pdf-theme=dist/pdf-theme.yml'
+
+# build Hugo site
 if [ ! -r ./node_modules ]; then
     docker run --rm --volume $PWD:/src -w "/src" capsulecorplab/hugo-asciidoctor-plantuml:0.76.5-alpine 'npm ci'
 fi

content/en/references/dist

@@ -0,0 +1 @@
+../../../dist

content/en/references/stakeholder-concerns-and-requirements.adoc

@@ -6,12 +6,4 @@ description: >
   Identifying stakeholder concerns & deriving top-level requirements.
 ---
 
-[plantuml, pkg-stakeholder-concerns, svg]
-....
-include::system-model/requirements/pkg-stakeholder-concerns.puml[]
-....
-
-[plantuml, pkg-requirements, svg]
-....
-include::system-model/requirements/pkg-requirements.puml[]
-....
+include::dist/tetra-requirements.adoc[]