HTS Bioinf - Documentation overview

Scope

This document describes how the bioinformatics documentation are organized and maintained, who is responsible for what and how it complies with the department's accreditation.

Terminology

OUS eHåndbok (EHB) - the official documentation system for OUS

Types of documentation

In general, we try to adhere to the Diátaxis framework for structuring our documentation. This means that we strive to separate:

procedures/how-to-guides - these typically become EHB docs if important
tutorials - these are brief and typically go into repo READMEs
reference - these are usually found in repo /docs or made from code and API descriptions
explanatory docs - these are written for overview and understanding

Diagrams

For diagrams, we prefer to use PlantUML for diagrams as code, or diagrams.net if we need to use an UI for drawing and want to keep the source files. Docs-builder will build diagrams as SVG files, and markdown documents can link to these SVG files. For simple code-based diagrams, we can also use Mermaid.js, which is supported by MkDocs Materials.

Drafts and work in progress

Some additional internal documents, like selected presentations, reports, standard figures, project specifications under work, and others, can also be found in our google-drive (for those who have access). A small subset of these, e.g. our project list, is shared by link.

Central place for all docs

Our documentation is written in Markdown. Source files are stored in the docs/ directories of code repositories, and in the docs-store repository. All the docs from separate repos are gathered by the docs-builder, then built and published as web pages, and finally made easily accessible from a common index page.

We define those Gitlab web-pages as our official documentation at any time. This documentation system meets the following requirements:

Security. The documents are protected on several levels:
Only members of the OUS bioinformatics group with two-factor authorization in Gitlab can access the respective docs repositories;
We take advantage of Gitlab's security measures, as described in the Open Source Program Agreement of Gitlab "Security and data protection" clause;
We additionally control the changes to be added by group members. No merges can be done without approval of system owner for each repository, explicitely defined in a CODEOWNERS file at the root of each repository (see Bioinformatics group roles for system owner role description and who holds this role for each system);
No sensitive information is contained in the documents. In addition, at any commit an automatic check for "secrets" is run to make sure no sensitive information is commited to the web-pages by mistake.
Integrity and availability:
The docs web-pages are accessible to anyone with a valid URL link;
Gitlab ensures service availability, as described here;
Version control and changelog:
The docs on the central web-pages are based on the main/master branch of the repos that are collected by docs-builder, in particular docs-store;
Each document in the central web-pages is uniquely identified by its full filename (URL);
We control the versions of the documents: the branch used to get docs from each repo is set in the docs-builder JSON configuration file and defaults to main;
We put in place clear procedures defining how and when the versions in EHB should be incremented (see synchronization with EHB and definition of significant changes below);
We control when the new versions of documents are released. The default branch in docs-store is main, meaning that, by default, merges go straight to production. If we need to await publishing to the official docs, we can stage the changes in dev or other release branches and coordinate when it will be released and published;
All the changes (and who made them) are tracked in the histories of the respective Gitlab repositories' (docs-store and index of docs-builder) as well as a manually maintained changelog in the corresponding EHB documents (see below).

OUS eHåndbook

Since we must comply to the hospital's documentation procedures (in particular meeting the requirements for ISO-15189), we coordinate our central web-repository for docs with EHB as described below.

Only important how-to-do-step-by-step procedures should feature in EHB.
We maintain the docs-store documentation repository and follow the bioinformatics procedures described there. Others can freely access the up-to-date production procedures via links in EHB to central documentation web-pages.
For each procedure in EHB there is one and only one corresponding procedure in docs-store.
The EHB documents include:
identical title to that in docs-store;
changelog of significant updates - date and short description of the changes introduced;
short summary of the procedure's scope and content;
link to the central documentation web-page.
The docs-store repository in Gitlab contains a table (for our internal use only, not published to the pages) with all documents in the docs-store and all corresponding EHB documents ids as well as their titles.
An important consequence of this documentation strategy is that the in-depth description of each procedure exists in one place only, leaving no room for divergence.
We define changes as significant (those that are reflected in the changelog in the EHB document) when:
they involve structural changes in our systems
they involve changes in the way we work
they include changes in the document's title
they concern a registered "avvik" (i.e., a non-conformity). Typos or grammatical errors rectifications, rephrasing or restructuring of the documents for improved readability without content changes are not considered significant changes.
The unit leader must approve the significant changes to EHB (manually added changelog) before those are published in the central web-pages.
We still use the "lesekvittering" (read-signing) in EHB to keep track of who has read what.

Process of synchronization of central documents and EHB

Everyone shall work to keep the documentation up to date in docs-store as well as the docs directories of the individual repositories.
The system owners (see systems description and Bioinf Group roles) are in particular responsible for documentation related to their system.
The bioinformatic coordinator is the owner of the documentation system as a whole.
Each system owner revises the procedures related to their domain every three months using the table of documents and corresponding EHB doc ids in docs-store.
As a result they can:
create issues for team members (including but not limited to themselves) to correct, improve or write missing documentation;
if this is relevant for EHB then:
- in case of new procedures, create corresponding EHB documents with the same title, a short description and a link to the central documentation web page;
- if procedures are reorganized - merged, split or renamed, reproduce such changes in EHB;
- for procedures already existing in EHB and with significant updates in the content, update the changelog in EHB;
- reset EHB "lesekvitteringer" on any significant changes;
update the procedures table in docs-store with changes if necessary;
collect and present to the team in a systematic way the changes in the procedures that happened since the last review;
highlight the procedures that need to be revisited and read again (with "lesekvittering") if the changes are conspicuous enough;
The system owners can delegate EHB updates to the team members with clear instructions.
The unit leader must approve significant updates to EHB documents before publication.