Refactor(docs): apply Diataxis

.github/workflows/mkdocs.yml

@@ -98,7 +98,7 @@ jobs:
           branch: main
           event: push
           name: coverage-report
-          path: docs/tests/coverage
+          path: docs/reference/coverage
 
       - name: Deploy docs
         uses: mhausenblas/mkdocs-deploy-gh-pages@master

docs/.pages

@@ -1,10 +1,6 @@
 nav:
-  - Home:
-      - README.md
-      - enrollment-pathways
-  - getting-started
-  - product-and-design
-  - development
-  - tests
-  - configuration
-  - deployment
+  - Overview: index.md
+  - explanation
+  - reference
+  - how-to
+  - tutorials

docs/deployment/README.md → docs/explanation/deployment.md

@@ -15,6 +15,37 @@ Registry (GHCR)][ghcr]. It also deploys to the Azure Web App, telling Azure to r
 
 You can view what Git commit is deployed for a given environment by visitng the URL path `/static/sha.txt`.
 
+The GitHub Actions deployment workflow configuration lives at [`.github/workflows/deploy.yml`][deploy].
+
+!!! info
+
+    The entire process from GitHub commit to full redeploy of the application can take from around 5 minutes to 10 minutes
+    or more depending on the deploy environment. Have patience!
+
+## Deployment steps
+
+The workflow is [triggered][gh-actions-trigger] with a `push` to the `main` branch or when a release candidate or release tag is created on any branch. It also responds to the `workflow_dispatch` event to allow manually triggering via the GitHub Actions UI.
+
+When a deployment workflow runs, the following steps are taken:
+
+### 1. Checkout code
+
+From the tip of the corresponding branch (e.g. `main`) or the tagged commit
+
+### 2. Authenticate to GHCR
+
+Using the `github.actor` and built-in `GITHUB_TOKEN` secret
+
+### 3. Build and push image to GitHub Container Registry (GHCR)
+
+Build the root [`Dockerfile`][dockerfile], tagging with the SHA from the HEAD commit or tagged commit.
+
+Push this image:tag into [GHCR][ghcr].
+
+### 4. App Service deploy
+
+Push the new image:tag to the Azure App Service instance.
+
 ## Configuration
 
 Sensitive [configuration settings](../configuration/README.md) are maintained as Application Configuration variables in Azure,
@@ -32,6 +63,8 @@ Docker images for each of the deploy branches are available from GitHub Containe
 [app-service-containers]: https://docs.microsoft.com/en-us/azure/app-service/configure-custom-container
 [app-service]: https://docs.microsoft.com/en-us/azure/app-service/overview
 [deploy-workflow]: https://github.com/cal-itp/benefits/blob/main/.github/workflows/deploy.yml
-[dockerfile]: https://github.com/cal-itp/benefits/blob/main/Dockerfile
 [az-webapp]: https://azure.microsoft.com/en-us/services/app-service/containers/
 [ghcr]: https://github.com/features/packages
+[deploy]: https://github.com/cal-itp/benefits/blob/main/.github/workflows/deploy.yml
+[dockerfile]: https://github.com/cal-itp/benefits/blob/main/appcontainer/Dockerfile
+[gh-actions-trigger]: https://docs.github.com/en/actions/reference/events-that-trigger-workflows

docs/deployment/troubleshooting.md → docs/how-to/troubleshooting.md

@@ -40,8 +40,6 @@ You can troubleshoot Sentry itself by [turning on debug mode](../../configuratio
 
 ## Specific issues
 
-This section serves as the [runbook](https://www.pagerduty.com/resources/learn/what-is-a-runbook/) for Benefits.
-
 ### Terraform lock
 
 [General info](https://developer.hashicorp.com/terraform/language/state/locking)

docs/README.md → docs/index.md

@@ -1,5 +1,79 @@
 # Project overview
 
+## Current work
+
+We do sprint planning and track day-to-day work on our [Project Board][board].
+
+See our [Milestones][milestones] for current work tracked against specific features and different enrollment pathways.
+
+## Product roadmap
+
+Our product roadmap captures what we're currently building, what we've built, and what we plan to build in the future. We update it at the end of each quarter or when priorities change.
+
+```mermaid
+timeline
+    title Cal-ITP Benefits Product Roadmap
+%% Cal-ITP Benefits Epics (2024)
+          section 2024
+
+          Q1<br>Complete
+          : Benefits admin tool (foundation)
+          : Deploy SBMTD Reduced Fare Mobility ID enrollment pathway
+          : Migrate to Littlepay Backoffice API
+
+          Q2<br>Complete
+          : Support for expiring benefits (low-income)
+          : Improved UX for agency card enrollment
+          : Improved UX for application error states
+
+          Q3<br>Complete
+          : Deploy low-income riders enrollment pathway
+          : Benefits admin tool (agency users)
+          : Benefits admin tool (in-person eligibility verification)
+
+          Q4<br>Complete
+          : Deploy Medicare cardholder enrollment pathway
+          : Support for multiple identity providers (Medicare.gov)
+
+%% Cal-ITP Benefits Epics (2025)
+          section 2025
+
+          Q1<br>Complete
+        : Front-end enhancements and optimization
+        : Deploy in-person enrollments
+        : Utilize CDT Identity Gateway connection library
+
+          Q2<br>Now
+        : Support for multiple transit processors (Enghouse)
+        : Enhanced Veteran eligibility checks (disability status)
+
+          Q3<br>Next
+        : Support for additional identity provider
+        : Benefits admin tool (user management)
+        : Benefits admin tool (agency configuration)
+
+          Q4<br>Projected
+        : Single eligibility check across multiple benefit options
+        : Eligibility check for individuals with disabilities (CA DMV)
+        : Support for Discover and American Express cards
+
+%%{
+  init: {
+    'logLevel': 'debug',
+    'theme': 'default' ,
+    'themeVariables': {
+      'cScale0': 'orange',
+      'cScaleLabel0': 'black',
+      'cScale1': 'yellow',
+      'cScaleLabel1': 'black'
+    }
+  }
+}%%
+```
+
+[board]: https://github.com/orgs/cal-itp/projects/8/views/1
+[milestones]: https://github.com/cal-itp/benefits/milestones
+
 This website provides technical documentation for the [`benefits`][benefits-repo] application from the
 [California Integrated Travel Project (Cal-ITP)][calitp].
 

docs/reference/.pages

@@ -0,0 +1,3 @@
+nav:
+  - ...
+  - Coverage report: ./reference/coverage