Restructure

docs/getting-started/services.md → docs/get-started/services.md

@@ -20,7 +20,7 @@ Make sure that you download the correct version of Docker. If you have a newer A
 
 Creating a [Docker account](https://hub.docker.com/signup) will give you a higher download limit. For anonymous users, the rate limit is set to 100 pulls per 6 hours per IP address but for authenticated users, it's 200 pulls per 6 hour period.
 
-We have a set way of working and [standards for our containers](../technology/containers.md) to ensure security and consistency.
+We have a set way of working and [standards for our containers](../technology/infrastructure//containers.md) to ensure security and consistency.
 
 ## GovWifi
 

docs/technology/python.md → docs/technology/backend/python.md

@@ -1,9 +1,9 @@
 # Python
 
 1. **Version**
-    1. The version of Python used SHOULD be 3.11
+    1. The version of Python used SHOULD be 3.11 or above
     1. The version of Python used MUST be 3.8 or above
-    1. Python projects SHOULD use one of the [TNA base Docker images](../resources/docker-images.md)
+    1. Python projects SHOULD use one of the [TNA base Docker images](../../resources/docker-images.md)
 1. **Style/linting**
     1. Python code MUST be styled with [Black](#black), [Flake8](#flake8) and [isort](#isort)
     1. The maximum [cyclomatic complexity](https://en.wikipedia.org/wiki/Cyclomatic_complexity) of the code MUST be no larger than 20
@@ -15,8 +15,10 @@
     1. Python applications MUST use one of the approved [frameworks](#frameworks)
 1. **Packages**
     1. Python packages SHOULD be made using pip
-    1. Python packages SHOULD be deployed to [PyPI](../third-party/pypi.md)
+    1. Python packages SHOULD be deployed to [PyPI](../../third-party/pypi.md)
     1. Python packages COULD be hosted in [AWS CodeArtifact](https://aws.amazon.com/codeartifact/)
+1. **Security**
+    1. A CSP SHOULD be set up
 
 ## Black
 
@@ -72,11 +74,11 @@ If using the `tna-python-dev` Docker image, [this isort configuration is include
 
 Use either [Flask](https://flask.palletsprojects.com/), [Django](https://www.djangoproject.com/) or [FastAPI](https://fastapi.tiangolo.com/) for your Python applications.
 
-| Framework                                   | Best choice for making                                                                     |
-| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| [Flask](https://flask.palletsprojects.com/) | Applications with a UI (can use [tna-frontend-jinja](../resources/tna-frontend-jinja.md)) |
-| [Django](https://www.djangoproject.com/)    | Applications that need to work with data and databases                                     |
-| [FastAPI](https://fastapi.tiangolo.com/)    | RESTful JSON APIs                                                                          |
+| Framework                                   | Best choice for making                                                                       |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| [Flask](https://flask.palletsprojects.com/) | Applications with a UI (can use [tna-frontend-jinja](../../resources/tna-frontend-jinja.md)) |
+| [Django](https://www.djangoproject.com/)    | Applications that need to work with data and databases                                       |
+| [FastAPI](https://fastapi.tiangolo.com/)    | RESTful JSON APIs                                                                            |
 
 ## Tools and libraries
 

docs/technology/css.md → docs/technology/frontend/css.md

@@ -1,7 +1,7 @@
 # CSS
 
 1. **Approach**
-    1. CSS MUST be treated as a [progressive enhancement](../ways-of-working/progressive-enhancement.md)
+    1. CSS MUST be treated as a [progressive enhancement](../../ways-of-working/progressive-enhancement.md)
     1. CSS MUST be served as a static file and MUST NOT be compiled at runtime
     1. Compiled CSS MUST NOT contain a source file map in the `.css` file itself
     1. Compiled CSS SHOULD contain a link to a separate source file (`.map.css`)
@@ -43,7 +43,7 @@ The CSS methodology we use is [BEM](https://getbem.com/).
 
 On 4th February 2021, frontend developers met to agree a CSS methodology. Having considered a recommendation for utility CSS (as represented in [tailwindcss](https://tailwindcss.com/)) and results of the most recent [state of CSS survey](https://2020.stateofcss.com/en-US/technologies/), the team agreed that the BEM methodology would best reflect the needs of the team at this time.
 
-[TNA Frontend](../resources/tna-frontend.md) uses a mix of BEM and classless strategies. Simple "top-level" elements such as `<ul>` have a class (`tna-ul`) while the `<li>` elements within it do not, as the `<ul>` element should only contain `<li>`. For more information, see details of the [structure of TNA Frontend](https://github.com/nationalarchives/tna-frontend/wiki/Structure).
+[TNA Frontend](../../resources/tna-frontend.md) uses a mix of BEM and classless strategies. Simple "top-level" elements such as `<ul>` have a class (`tna-ul`) while the `<li>` elements within it do not, as the `<ul>` element should only contain `<li>`. For more information, see details of the [structure of TNA Frontend](https://github.com/nationalarchives/tna-frontend/wiki/Structure).
 
 ## Stylelint
 

docs/technology/html.md → docs/technology/frontend/html.md

@@ -1,7 +1,7 @@
 # HTML
 
 1. **Approach**
-    1. HTML-only users MUST be treated as [first-class citizens](https://en.wikipedia.org/wiki/First-class_citizen) ([Service standard - Progressive enhancement](../ways-of-working/progressive-enhancement.md))
+    1. HTML-only users MUST be treated as [first-class citizens](https://en.wikipedia.org/wiki/First-class_citizen) ([Service standard - Progressive enhancement](../../ways-of-working/progressive-enhancement.md))
 1. **Style**
     1. All HTML for National Archive applications MUST adhere to the [HTML5 standard](https://www.w3.org/TR/2011/WD-html5-20110405/)
     1. The `<html>` element SHOULD have a `lang` attribute
@@ -47,4 +47,4 @@ Acceptable file formats for videos are:
 | MP4    | `.mp4`    | `video/mp4`  |
 | WebM   | `.webm`   | `video/webm` |
 
-To use embedded media, refer to [YouTube](../third-party/youtube.md).
+To use embedded media, refer to [YouTube](../../third-party/youtube.md).

docs/technology/javascript.md → docs/technology/frontend/javascript.md

@@ -1,7 +1,7 @@
 # JavaScript
 
 1. **Approach**
-    1. JavaScript MUST only be used for [progressive enhancement](../ways-of-working/progressive-enhancement.md) - do not rely on libraries such as React, Vue or Angular
+    1. JavaScript MUST only be used for [progressive enhancement](../../ways-of-working/progressive-enhancement.md) - do not rely on libraries such as React, Vue or Angular
     1. JavaScript MUST be served as a static file and MUST NOT be compiled at runtime
     1. Compiled JavaScript MUST NOT contain a source file map in the `.js` file itself
     1. Compiled JavaScript SHOULD contain a link to a separate source file (`.map.js`)
@@ -25,7 +25,7 @@
     1. JavaScript tests SHOULD be written with [Jest](https://jestjs.io/)
 1. **Packages**
     1. JavaScript packages SHOULD be made using npm
-    1. JavaScript packages SHOULD be deployed to [npm](../third-party/npmjs.md)
+    1. JavaScript packages SHOULD be deployed to [npm](../../third-party/npmjs.md)
     1. If using NPM, packages MUST be published under the [`@nationalarchives` organisation]()
     1. JavaScript packages COULD be hosted in [AWS CodeArtifact](https://aws.amazon.com/codeartifact/)
     1. JavaScript MUST be compiled down to ES5 before distribution

docs/technology/index.md

@@ -2,21 +2,21 @@
 
 ## New applications
 
-New National Archive applications SHOULD be deployed to the [Public Cloud](aws.md) and use the following approved languages and tools:
+New National Archive applications SHOULD be deployed to the [Public Cloud](infrastructure/aws.md) and use the following approved languages and tools:
 
-- [HTML](html.md)
-- [JavaScript](javascript.md) - for either [progressive enhancement](../ways-of-working/progressive-enhancement.md) or for compiling web assets using tools like Webpack through NodeJS
-- [CSS](css.md)
-- [Python](python.md)
-- [Postgres](postgres.md)
-- [Docker](containers.md) - to create deployable containers
-- [Terraform](terraform.md) - to provision and manage infrastructure in the cloud
-- [Nginx](nginx.md) - to provide a reverse proxy in front of Docker containers
+- [HTML](frontend/html.md)
+- [JavaScript](frontend/javascript.md) - for either [progressive enhancement](../ways-of-working/progressive-enhancement.md) or for compiling web assets using tools like Webpack through NodeJS
+- [CSS](frontend/css.md)
+- [Python](backend/python.md)
+- [Postgres](database/postgres.md)
+- [Docker](infrastructure/containers.md) - to create deployable containers
+- [Terraform](infrastructure/terraform.md) - to provision and manage infrastructure in the cloud
+- [Nginx](infrastructure/nginx.md) - to provide a reverse proxy in front of Docker containers
 
 In addition to this, engineers COULD also use:
 
-- [TypeScript](javascript.md#typescript) - which must be compiled down to [JavaScript](javascript.md)
-- [SCSS](css.md#sassscss) - allows us to more easily write CSS
+- [TypeScript](frontend/javascript.md#typescript) - which must be compiled down to [JavaScript](frontend/javascript.md)
+- [SCSS](frontend/css.md#sassscss) - allows us to more easily write CSS
 
 Any other technologies MUST be proposed to and agreed by the [Technical Architects Group](../organisation/technical-architects-group.md) through the process of [requesting changes](https://nationalarchives.github.io/engineering-handbook/ways-of-working/documentation/#requesting-changes).
 

docs/technology/aws.md → docs/technology/infrastructure/aws.md

@@ -1,17 +1,17 @@
-# Amazon Web Services
-
-[Amazon Web Services](https://aws.amazon.com/) is the preferred Public Cloud platform for The National Archives and SHOULD be used. Providers such as Azure and Google GCP SHOULD NOT be used.
-
-In line with the [Government Cloud First policy](https://www.gov.uk/guidance/government-cloud-first-policy), serverless and/or managed service solutions are preferred and SHOULD be used. Server based services MAY be used but are NOT RECOMMENDED. Examples of serverless/managed services are API Gateway, DynamoDB, Lambda, S3, SNS, SQS, RDS, etc.
-
-Infrastructure within AWS MUST be managed via an IaC solution; [Terraform](terraform.md) is preferred. Where possible, modules SHOULD be shared and reused. Examples of existing Terraform module repositories include:
-
-- [da-terraform-modules](https://github.com/nationalarchives/da-terraform-modules)
-
-When developing services in the Public Cloud, best practices from the supplier MUST be followed.
-
-## Logging in to AWS
-
-Access to AWS SHOULD be via [IAM Identity Center](https://nationalarchivesuk.awsapps.com/start#/) for all staff members. To manage who can access accounts through IAM Identity Center, see [these guides](https://national-archives.atlassian.net/l/cp/1cCe2cVy) on Confluence.
-
-IAM Users SHOULD NOT be used to access the AWS Console or AWS API/SDK.
+# Amazon Web Services
+
+[Amazon Web Services](https://aws.amazon.com/) is the preferred Public Cloud platform for The National Archives and SHOULD be used. Providers such as Azure and Google GCP SHOULD NOT be used.
+
+In line with the [Government Cloud First policy](https://www.gov.uk/guidance/government-cloud-first-policy), serverless and/or managed service solutions are preferred and SHOULD be used. Server based services MAY be used but are NOT RECOMMENDED. Examples of serverless/managed services are API Gateway, DynamoDB, Lambda, S3, SNS, SQS, RDS, etc.
+
+Infrastructure within AWS MUST be managed via an IaC solution; [Terraform](terraform.md) is preferred. Where possible, modules SHOULD be shared and reused. Examples of existing Terraform module repositories include:
+
+- [da-terraform-modules](https://github.com/nationalarchives/da-terraform-modules)
+
+When developing services in the Public Cloud, best practices from the supplier MUST be followed.
+
+## Logging in to AWS
+
+Access to AWS SHOULD be via [IAM Identity Center](https://nationalarchivesuk.awsapps.com/start#/) for all staff members. To manage who can access accounts through IAM Identity Center, see [these guides](https://national-archives.atlassian.net/l/cp/1cCe2cVy) on Confluence.
+
+IAM Users SHOULD NOT be used to access the AWS Console or AWS API/SDK.

docs/ways-of-working/licences.md → docs/technology/standards/licences.md

@@ -10,7 +10,7 @@ You can use and include modules and resources which also use the MIT licence.
 
 You can use modules and resources which use either the Apache or BSD family of licences.
 
-Use package managers wherever possible such as [NPM](../third-party/npmjs.md) and [PyPI](../third-party/pypi.md).
+Use package managers wherever possible such as [NPM](../../third-party/npmjs.md) and [PyPI](../../third-party/pypi.md).
 
 If you include Apache or BSD-licenced work in your source code then you must also include:
 

docs/technology/standards/security.md

@@ -0,0 +1,8 @@
+# Security
+
+## Services
+
+- CSP
+- Environment variables
+
+## Infrastructure

docs/ways-of-working/progressive-enhancement.md

@@ -17,23 +17,23 @@ Remember, [not everyone has JavaScript](https://www.kryogenix.org/code/browser/e
 
 ### 1. Start with the HTML
 
-Taking into consideration the [HTML standards](../technology/html.md), create markup that will accomplish the user need without requiring CSS or JavaScript.
+Taking into consideration the [HTML standards](../technology/frontend/html.md), create markup that will accomplish the user need without requiring CSS or JavaScript.
 
-Add the appropriate attributes to ensure the HTML meets [accessibility standards](accessibility.md).
+Add the appropriate attributes to ensure the HTML meets [accessibility standards](../technology/standards/accessibility.md).
 
 ### 2. Embellish with CSS
 
-Add some styling in accordance with the [CSS standards](../technology/css.md) to enhance the component.
+Add some styling in accordance with the [CSS standards](../technology/frontend//css.md) to enhance the component.
 
 CSS shouldn't dictate the markup, although if you need more elements to achieve the style you need then add some extra HTML that you can hook into. Ensure the extra elements don't negatively affect the HTML-only solution.
 
-Check your styles across all our [supported browsers](browser-support.md) as CSS support can vary wildly.
+Check your styles across all our [supported browsers](../technology/standards/browser-support.md) as CSS support can vary wildly.
 
 Use [caniuse.com](https://caniuse.com/) to check support for CSS features.
 
 ### 3. Elaborate with JavaScript
 
-Use the [JavaScript standards](../technology/javascript.md) and add scripts which allow easier functionality.
+Use the [JavaScript standards](../technology/frontend/javascript.md) and add scripts which allow easier functionality.
 
 You can use JavaScript to add more features as long as the user can complete their action without the need for JavaScript. An example would be to use JavaScript to open and close a menu. The menu should be visible to all but JavaScript would allow you to collapse it and save some screen real estate.
 

docs/ways-of-working/version-control.md

@@ -15,7 +15,7 @@ A `README.md` written in markdown MUST be present and populated explaining the r
 
 The repository MUST contain a `LICENCE` or `LICENCE.txt` file.
 
-Read more about [licences](licences.md) at TNA.
+Read more about [licences](../technology/standards/licences.md) at TNA.
 
 ### Changelog
 

mkdocs.yml

@@ -4,41 +4,47 @@ repo_url: https://github.com/nationalarchives/engineering-handbook
 dev_addr: localhost:8888
 use_directory_urls: true
 nav:
-  - Home: index.md
-  - Getting started:
-    - getting-started/index.md
-    - Tools: getting-started/tools.md
-    - Services: getting-started/services.md
-    - Communication: getting-started/communication.md
+  - Home:
+    - index.md
+    - Get started:
+      - get-started/index.md
+      - Tools: get-started/tools.md
+      - Services: get-started/services.md
+      - Communication: get-started/communication.md
+    - Organisation:
+      - organisation/index.md
+      - Technical Architects Group: organisation/technical-architects-group.md
+      - Technical Governance Board: organisation/technical-governance-board.md
   - Technology:
     - technology/index.md
     - Frontend:
-      - HTML: technology/html.md
-      - JavaScript: technology/javascript.md
-      - CSS: technology/css.md
+      - HTML: technology/frontend/html.md
+      - JavaScript: technology/frontend/javascript.md
+      - CSS: technology/frontend/css.md
     - Backend:
-      - Python: technology/python.md
-      - Scala: technology/scala.md
+      - Python: technology/backend/python.md
+      - Scala: technology/backend/scala.md
     - Database:
-      - Postgres: technology/postgres.md
-    - Deployment:
-      - Docker: technology/containers.md
-      - Terraform: technology/terraform.md
-      - Nginx: technology/nginx.md
-    - Cloud:
-      - Amazon Web Services (AWS): technology/aws.md
+      - Postgres: technology/database/postgres.md
+    - Infrastructure:
+      - Amazon Web Services (AWS): technology/infrastructure/aws.md
+      - Docker: technology/infrastructure/containers.md
+      - Terraform: technology/infrastructure/terraform.md
+      - Nginx: technology/infrastructure/nginx.md
+    - Standards:
+      - Accessibility: technology/standards/accessibility.md
+      - APIs: technology/standards/api.md
+      - Browser support: technology/standards/browser-support.md
+      - Licences: technology/standards/licences.md
+      - Security: technology/standards/security.md
+      - Testing: technology/standards/testing.md
+      - URLs: technology/standards/url.md
   - Ways of working:
     - ways-of-working/index.md
     - Service standard: ways-of-working/service-standard.md
     - Progressive enhancement: ways-of-working/progressive-enhancement.md
     - Version control: ways-of-working/version-control.md
     - Documentation: ways-of-working/documentation.md
-    - Licences: ways-of-working/licences.md
-    - Testing: ways-of-working/testing.md
-    - APIs: ways-of-working/api.md
-    - URLs: ways-of-working/url.md
-    - Browser support: ways-of-working/browser-support.md
-    - Accessibility: ways-of-working/accessibility.md
     - Deployment: ways-of-working/deployment.md
     - Definition of done: ways-of-working/definition-of-done.md
   - Third party:
@@ -50,10 +56,6 @@ nav:
     - Docker registries: third-party/docker-registries.md
     - Analytics: third-party/analytics.md
     - YouTube: third-party/youtube.md
-  - Organisation:
-    - organisation/index.md
-    - Technical Architects Group: organisation/technical-architects-group.md
-    - Technical Governance Board: organisation/technical-governance-board.md
   - Resources:
     - resources/index.md
     - TNA Frontend: resources/tna-frontend.md