Skip to content

Technical Design

Jump to bottom
Russell McCreath edited this page Mar 7, 2024 · 1 revision

Overview

The document outlines the technical design implemented for this GitHub repository, containing the organisation's technical documentation, and the front-end PHS Data Science Knowledge Base.

Component Diagram

  1. Technical Documentation Repository
  2. PHS Data Science Knowledge Base Repository

Data Architecture

At time of writing, the repo is structured as below. Each directory is then pulled through to the Knowledge Base UI with contained documents showing under the respective directory.

├── Glossary              // excluded from normal UI build
│   ├── README.md
├── Information Sharing   // 
│   ├── README.md         // acts as the landing page for each directory topic
│   ├── ...md
├── Posit Infrastructure  // 
│   ├── README.md         // acts as the landing page for each directory topic
│   ├── ...md
├── Python                // 
│   ├── README.md         // acts as the landing page for each directory topic
│   ├── ...md
├── R                     // 
│   ├── README.md         // acts as the landing page for each directory topic
│   ├── ...md
├── Version Control       // 
│   ├── README.md         // acts as the landing page for each directory topic
│   ├── ...md
└── README.md             // excluded from normal UI build

Adding new directories

It's possible to add a new directory, to hold a new 'section'/topic of documents. This should

  • Be in title case
  • Not exceed 20 characters
  • Have a defined use case that minimises overlap with other existing directories

Adding new documents

Through the normal use of the repo, the expectation is that documents will be updated and new ones added. Where a new document is added, it should follow the below guidance:

  • File name should be human readable, in title case, with spaces. The name is directly used in the navigation bar, so should be as descriptive as possible.
  • Where the document is a step-by-step set of instructions that are universal, the file name should start with "How to ".
  • Where the document is a recommended practice, the file name should start with "Recommended ".
  • File structure should follow standard markdown linting rules.
  • The purpose of the document should be set out first, identifying what the document is for and what it covers.
  • Content of the document should be written in a way that is accessible to all users, with no jargon or technical terms. Where possible, links to other documents should be used to explain concepts. If suitable, documentation to learn about concepts can be developed separately from instructions to perform a task.
  • Within-repo links should be relative to the root of the repo. For example, a link to the Posit Infrastructure directory would be Posit Infrastructure.
  • External links should be absolute links, with the full URL. For example, a link to the Public Health Scotland website would be Public Health Scotland.

Other contribution guidance is available here: https://github.com/Public-Health-Scotland/technical-docs/blob/main/CONTRIBUTING.md

Clone this wiki locally