Merge pull request #41 from VKGL-Kwaliteit/feature/full_review

Full review #1
VKGL-Kwaliteit · Apr 5, 2024 · 4fcdeb6 · 4fcdeb6
2 parents f3b6087 + 770b7f4
commit 4fcdeb6
Show file tree

Hide file tree

Showing 14 changed files with 346 additions and 295 deletions.
diff --git a/README.md b/README.md
@@ -1,9 +1,10 @@
 # BioinformaticaVeldnorm
+
 # HPC wiki
 
 ## Description
 
-Fieldnorm for Bioinformatics within Medical Laboratories
+Field standard for Bioinformatics within Medical Laboratories
 
 Which procedures need to be documented for the development of pipelines, workflows or tools.
 
@@ -54,17 +55,21 @@ pnpm install
 ```
 
 ## Development
-You want to contribute the VKGL Bioinformatics Fieldnorm, great! 
-Strictly speaking the scheme below is not enforced, however strongly recommended to keep your changes grouped together 
+
+You want to contribute the VKGL Bioinformatics field standard, great!
+Strictly speaking the scheme below is not enforced, however strongly recommended to keep your changes grouped together
 in your git history. Commit your changes, do not hesitate to do that often, however make understandable commit messages.
-What is enforced in the end is a code review process to keep information accurate. 
+What is enforced in the end is a code review process to keep information accurate.
 
 ### Git flow
-Using the [git flow](https://jeffkreeftmeijer.com/git-flow/) scheme is strongly 
+
+Using the [git flow](https://jeffkreeftmeijer.com/git-flow/) scheme is strongly
 encouraged to keep the history of the project orderly and concise.
-From a practical point of view using the git flow plugin is the easiest way (but not strictly necessary). 
+From a practical point of view using the git flow plugin is the easiest way (but not strictly necessary).
+
 1. Install the [plugin](https://github.com/nvie/gitflow).
 2. Init the plugin:
+
 ```bash
 git flow init
 # production:  main
@@ -74,59 +79,71 @@ git flow init
 # release:     release/
 # hotfix:      not used (keep default)
 # support:     not used (keep default)
-# version tag prefix: [] 
+# version tag prefix: []
 ```
 
 #### Start your addition
-Additions to our Fieldnorm should be handed in via a feature branch. The feature branch should have a clear name 
+
+Additions to our field standard should be handed in via a feature branch. The feature branch should have a clear name
 that shortly describes your addition. Feature branches are located under feature/ in our repository.
-After initialization of the plugin starting a feature branch to write your addition to the Fieldnorm is easy:
+After initialization of the plugin starting a feature branch to write your addition to the field standard is easy:
+
 ```bash
 git flow feature start "GREAT ADDITION"
 ```
-Pages are written using the [markup language markdown](https://www.markdownguide.org/).  
+
+Pages are written using the [markup language markdown](https://www.markdownguide.org/).
 Some handies (feel free to add if you like more):
 
 | Syntax                                         | Description                                                         |                              Example                              |
-|:-----------------------------------------------|:--------------------------------------------------------------------|:-----------------------------------------------------------------:|
-| # H1                                           | Header line                                                         |                              *table*                              |
-| - bullet                                       | Bullet points                                                       |                              *table*                              |
-| \*\*bold**                                     | Bold                                                                |                             **bold**                              |
-| \*italic                                       | Italic                                                              |                             *italic*                              |
+| :--------------------------------------------- | :------------------------------------------------------------------ | :---------------------------------------------------------------: |
+| # H1                                           | Header line                                                         |                              _table_                              |
+| - bullet                                       | Bullet points                                                       |                              _table_                              |
+| \*\*bold\*\*                                   | Bold                                                                |                             **bold**                              |
+| \*italic                                       | Italic                                                              |                             _italic_                              |
 | \`command`                                     | Code                                                                |                             `command`                             |
-| \```bash commands ```                          | Code block (can use syntax highlighting by indicating the language) |                    ```this is a code block ```                    |
+| \```bash commands ```                          | Code block (can use syntax highlighting by indicating the language) |                      `this is a code block `                      |
 | \[text](link)                                  | Hyperlink                                                           | [extended syntax](https://www.markdownguide.org/extended-syntax/) |
-| \![alt text]\(image_file.png "Optional title") | Image                                                               |                ![VKGL logo](VKGL-logo.webp "VKGL")                |
+| \![alt text]\(image_file.png "Optional title") | Image                                                               |                ![VKGL logo](VKGL-logo.webp 'VKGL')                |
 
 #### Test your additions
+
 To start the development version first navigate to the project folder. Next run the pnpm command:
+
 ```bash
 pnpm docs:dev
 ```
+
 This starts a local development version that can be viewed in a browser via `localhost:8080`.
 
 #### Finish your addition
-You can push your feature to the [main repository](https://github.com/VKGL-Kwaliteit/BioinformaticaVeldnorm)  if you have access or to your own fork. 
-After you are finished and everything looks decent enough you can hand in your addition by creating a pull 
+
+You can push your feature to the [main repository](https://github.com/VKGL-Kwaliteit/BioinformaticaVeldnorm) if you have access or to your own fork.
+After you are finished and everything looks decent enough you can hand in your addition by creating a pull
 request in [github](https://github.com/VKGL-Kwaliteit/BioinformaticaVeldnorm).
 After a code review by one of the team members your additions will be merged to our develop branch.
 
 ### Release procedure
+
 Once in a while, the team will revise the current document, and might release a new version of this norm.
-A revision of the norm document will include a release review by the team, during which the develop will be 
+A revision of the norm document will include a release review by the team, during which the develop will be
 merged with the main branch. An update on the main branch will trigger a new version on the website.
 
 #### Start a release
-The release procedure will start branching the main branch and merge the develop into this. This is done using 
+
+The release procedure will start branching the main branch and merge the develop into this. This is done using
 the git flow plugin, using the following procedure:
+
 ```bash
 git flow release start "VERSION NORM RELEASE CANDIDATE"
 ```
 
 #### Create the release request
-A pull request for this release candidate onto the main branch will be created by the team, after which a 
+
+A pull request for this release candidate onto the main branch will be created by the team, after which a
 last round of feedback is initiated.
 
 #### Release
-If the team agrees the release candidate is ready for publication the pull request is merged, after which it 
-will be publicated on the [website](https://vkgl-kwaliteit.github.io/BioinformaticaVeldnorm/). 
+
+If the team agrees the release candidate is ready for publication the pull request is merged, after which it
+will be publicated on the [website](https://vkgl-kwaliteit.github.io/BioinformaticaVeldnorm/).
diff --git a/docs/.vuepress/bar/sidebar.ts b/docs/.vuepress/bar/sidebar.ts
@@ -15,6 +15,7 @@ export const sidebarImport: SidebarConfig = {
         '/fieldnorm/soups.md',
         '/fieldnorm/abbreviations.md',
         '/fieldnorm/references.md',
+        '/fieldnorm/contact.md',
       ],
     },
   ]

diff --git a/docs/fieldnorm/abbreviations.md b/docs/fieldnorm/abbreviations.md
@@ -1,6 +1,24 @@
-# Abbreviations
+# Abbreviations and Definitions
 
-- IEC: International Electrotechnical Commission
-- ISO: International Organization for Standardization
-- IVDR: In Vitro Diagnostics Regulation
-- QMS: Quality Management System
+## Abbreviations
+-   GIAB: Genome In A Bottle
+-   FMEA: Failure Mode and Effects Analysis
+-   IEC: International Electrotechnical Commission
+-   IGV: Integrative Genomics Viewer
+-   IMDRF: International Medical Device Regulators Forum
+-   ISO: International Organization for Standardization
+-   IVDR: In Vitro Diagnostics Regulation
+-   MDR: Medical Device Regulation
+-   MDSW: Medical Device SoftWare
+-   QMS: Quality Management System
+-   SAFER: Stop, Assess, Formulate, Execute, and Review
+-   SaMD: Software as a Medical Device
+-   SDLC: Software Development Life Cycle
+-   SMART: Specific, Measurable, Achievable, Realistic, and Timely
+-   SOP: Standard Operating Procedure
+-   SOUP: Software of Unknown Provenance
+-   WES: Whole Exome Sequencing
+
+## Definitions
+-   End users - The group that will actually use the software developed by bioinformaticians
+-   Git - A distributed version control system that tracks changes in any set of computer files. 
diff --git a/docs/fieldnorm/configuration_management.md b/docs/fieldnorm/configuration_management.md
@@ -1,8 +1,9 @@
 # Configuration management
+
 Configuration management is essential when keeping track of different versions of software that may exhibit different capabilities and dependencies. Therefore, a concise regulation of development versioning should be in place. Each release of a new version of software should be identifiable by a specific version number for reference purposes. These version releases may be related to updates of different sizes (e.g. they may concern a major change in structure and capability, or they may just entail a small bugfix). A standardized versioning scheme should be implemented for software components. The version number should follow the format `major.minor.patch`, adhering to the Semantic Versioning principles (see [https://semver.org](https://semver.org)). This number may be extended if necessary (e.g. `major.minor.patch.build`), so long as it at least contains the major, minor and patch numbers and it is documented clearly.
 
-- **Major changes:** In general, major version updates indicate significant changes that are not backward compatible. They may include structural changes or changed dependencies.
-- **Minor changes:** Minor version updates usually represent the addition of new features or functionality without breaking compatibility with the existing system.
-- **Patches:** Patches address critical bugs and issues that require immediate attention. They do not introduce new features and can be used to quickly restore errors in code that were not detected during testing. They may also include small updates with little change to the software. 
+-   **Major changes:** In general, major version updates indicate significant changes that are not backward compatible. They may include structural changes or changed dependencies.
+-   **Minor changes:** Minor version updates usually represent the addition of new features or functionality without breaking compatibility with the existing system.
+-   **Patches:** Patches address critical bugs and issues that require immediate attention. They do not introduce new features and can be used to quickly restore errors in code that were not detected during testing. They may also include small updates with little change to the software.
 
 The exact definitions of these kinds of updates may differ between workplaces and should be discussed and documented clearly.
diff --git a/docs/fieldnorm/contact.md b/docs/fieldnorm/contact.md
@@ -0,0 +1,22 @@
+# Contact
+
+With the arrival of the IVDR, and the need for audits on bioinformatics by competent authorities such as the Raad voor Accreditatie (NL), there was a need for a field standard about bioinformatics, as from the ISO-15189 it is unclear what to audit for bioinformatics. This field standard has been initiated by Hanneke van Deutekom, member of the quality committee of the [VKGL](https://vkgl.nl/nl/) and technical assessor bioinformatics at the Raad voor Accreditatie.
+
+Bioinformaticians from all the genetic medical laboratories in the Netherlands gathered to discuss the processes used to develop software. The processes within the different centers and the IEC-62304 were used as a guidance to create this field standard for bioinformatics.
+
+The following people were involved with writing and reviewing.
+
+**Tobias Beers**, Department of Pathology, Antoni van Leeuwenhoek – Netherlands Cancer Institute (AvL-NKI), Amsterdam, the Netherlands
+**Roxane E. Boyer**, Department of Human Genetics, Amsterdam University Medical Center, Amsterdam, the Netherlands
+**Hanneke W. M. van Deutekom**, Department of Genetics, University Medical Center Utrecht, Utrecht, the Netherlands
+**Robert F. Ernst**, Department of Genetics, University Medical Center Utrecht, Utrecht, the Netherlands
+**Geert Geeven**, Department of Clinical Genetics, Erasmus MC, University Medical Center Rotterdam, Rotterdam, the Netherlands
+**Bart de Koning**, Department of Clinical Genetics, Maastricht University Medical Center+, Maastricht, the Netherlands
+**Thomas Leenders**, Department of Human Genetics, Radboud University Medical Center, Nijmegen, the Netherlands
+**Rick Medemblik**, Department of Human Genetics, Amsterdam University Medical Center, Amsterdam, the Netherlands
+**Pieter Neerincx**, Department of Genetics, University Medical Center Groningen, Groningen, the Netherlands
+**Ruben H.P. Vorderman**, Department of Biomedical Data Sciences, Leiden University Medical Center, Leiden, the Netherlands
+
+You can provide feedback for this field standard, or leave comments or suggestions for improvement by filing an [issue](https://github.com/VKGL-Kwaliteit/BioinformaticaVeldnorm/issues), which is open to everybody.
+
+The first version was released on 19th of April 2024.