docs: improve the introduction page (#23)

dvsa · Mar 5, 2024 · ac618fa · ac618fa
1 parent 960e071
commit ac618fa
Show file tree

Hide file tree

Showing 12 changed files with 61 additions and 21 deletions.
diff --git a/docs/app/_category_.json b/docs/app/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "App",
+  "position": 20,
+  "collapsed": false
+}
diff --git a/docs/app/overview.md b/docs/app/overview.md
@@ -0,0 +1 @@
+# Overview
diff --git a/docs/assets/languages/docker.svg b/docs/assets/languages/docker.svg
diff --git a/docs/assets/languages/markdown.svg b/docs/assets/languages/markdown.svg
diff --git a/docs/assets/languages/php.svg b/docs/assets/languages/php.svg
diff --git a/docs/assets/languages/terraform.svg b/docs/assets/languages/terraform.svg
diff --git a/docs/assets/languages/typescript.svg b/docs/assets/languages/typescript.svg
diff --git a/docs/infrastructure/_category_.json b/docs/infrastructure/_category_.json
@@ -0,0 +1,5 @@
+{
+  "label": "Infra",
+  "position": 30,
+  "collapsed": false
+}
diff --git a/docs/infrastructure/overview.md b/docs/infrastructure/overview.md
@@ -0,0 +1 @@
+# Overview
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -3,8 +3,16 @@ sidebar_position: 1
 slug: /
 ---
 
-# Overview
+# Introduction
 
-The VOL application documentation. This is a work-in-progress.
+The Vehicle Operator Licence (VOL) application documentation.
 
-The epic to create documentation is [here](https://dvsa.atlassian.net/browse/VOL-4970).
+This repository is a mono-repository, and contains the following:
+
+-   ![PHP](./assets/languages/php.svg) Application code (`/app`)
+-   ![Markdown](./assets/languages/markdown.svg) Documentation (`/docs`)
+-   ![Docker](./assets/languages/docker.svg) Application containers (`/infra/docker`)
+-   ![Terraform](./assets/languages/terraform.svg) Infrastructure As Code (`/infra/terraform`)
+-   ![TypeScript](./assets/languages/typescript.svg) Static site hosting the documentation (`/website`)
+
+The epic to expand documentation is [here](https://dvsa.atlassian.net/browse/VOL-4970).
diff --git a/docs/rfc/rfc-001-mono-repository.md b/docs/rfc/rfc-001-mono-repository.md
@@ -35,23 +35,24 @@ GitHub Action workflows will be designed to execute only on sub-projects with de
 
 -   Create a new repository named `vol-app`.
 -   Adopt a directory structure similar to the following:
-    ```
-    |__ `.github`
-    |       |__ `workflows/`
-    |            |__ `ci.yaml`
-    |            |__ `cd.yaml`
-    |__ `app`
-            |__ `api/`
-            |__ `internal/`
-            |__ `selfserve/`
-    |__ `infra` (optional)
-            |__ `terraform/`
-    |__ `vendor-bin/`
-            |__ `phpcs`
-            |__ `phpstan`
-            |__ `psalm`
-    |__ `.editorconfig`
-    |__ `docker-compose.yaml`
-    |__ ...
+    ```js
+    |-- `.github`
+    |       |-- `workflows/`
+    |       |    |-- `ci.yaml`
+    |       |    |-- `cd.yaml`
+    |-- `app`
+    |       |-- `api/`
+    |       |-- `internal/`
+    |       |-- `selfserve/`
+    |-- `infra`
+    |       |-- `terraform/` (Optional)
+    |       |-- `docker/`
+    |-- `vendor-bin/`
+    |       |-- `phpcs`
+    |       |-- `phpstan`
+    |       |-- `psalm`
+    |-- `.editorconfig`
+    |-- `docker-compose.yaml`
+    |-- ...
     ```
 -   Import repositories while retaining their git history for relevant commits during the merge.
diff --git a/website/src/css/custom.css b/website/src/css/custom.css
@@ -37,3 +37,7 @@
 [data-theme="dark"] .docusaurus-highlight-code-line {
   background-color: rgba(0, 0, 0, 0.3);
 }
+
+img {
+  vertical-align: middle;
+}