Add README and CONTRIBUTING guides

Author: spikeheap

CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# How to contribute to this site
+
+This website is built using [Docusaurus](https://docusaurus.io/) and is hosted on GitHub Pages using GitHub Actions to build and publish.
+
+
+## Getting set up
+
+### Prerequisites
+
+You'll need the following to run the site locally and make changes easily:
+
+1. Modern Node (check the `node-version` in [the deployment pipeline](./.github/workflows/deploy.yml) to see what we're targeting).
+2. [EditorConfig](https://editorconfig.org/) configured for your editor (optional). EditorConfig ensures your changes are consistent with the repository standards before you raise a pull request.
+
+> ℹ️ For VSCode there's an official [EditorConfig for VS Code](https://marketplace.visualstudio.com/items?itemName=EditorConfig.EditorConfig) plugin.
+
+
+### Install dependencies
+
+```bash
+npm install
+```
+
+## Local Development
+
+```bash
+npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+> ⚠️ The local development server doesn't build the search index. To test this locally, you'll need to build and serve the site (see below).
+
+## Build
+
+```bash
+npm run build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service or using:
+
+```bash
+npm run serve
+```
+
+## Deployment
+
+Deployment is done automatically through GitHub Actions to GitHub Pages.
+
+### Break-glass deployment steps
+
+Using SSH:
+
+```bash
+USE_SSH=true npm run deploy
+```
+
+Not using SSH:
+
+```bash
+GIT_USER=<Your GitHub username> npm run deploy
+```

README.md

@@ -1,41 +1,35 @@
-# Website
+# Hackney Development System
 
-This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
+The [Hackney Development System](https://playbook.hackney.gov.uk/) is the home of the Hackney development team's documentation, and details how we work as well as technical and architectural documentation.
 
-### Installation
+Project-specific documentation doesn't generally live here, and will be found alongside the code in the relevant repositories. There are exceptions, for example the API specifications section seeks to provide a central directory of Hackney's APIs.
 
-```
-$ yarn
-```
+## Architecture
 
-### Local Development
+This website is built using [Docusaurus](https://docusaurus.io/) and is hosted on GitHub Pages using GitHub Actions to build and publish.
 
-```
-$ yarn start
-```
+Before 2024 this site was built and deployed as a series of small static sites with independent repositories, build tooling, and styling.
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+The site is now a single repository and build pipeline, which reduces the maintenance burden to upgrade dependencies and gives us more flexibility to alter and add to the structure.
 
-### Build
+### Local search
 
-```
-$ yarn build
-```
+This site provides a search bar provided by an in-browser JavaScript library. This differs from the Docusaurus-supported default which relies on an Algolia account. We choose local-only search so we don't have to manage the Algolia account or rely on a third party service.
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+### Google Analytics
 
-### Deployment
+In order to measure the effectiveness of our documentation and identify stale or ineffective content we use Google Analytics, which records to a property in our Google Workspace.
+
+### Ownership
 
-Using SSH:
+Most of the content on this site belongs to Hackney's development community as a whole. Some sections, for example the Data Platform Playbook, belong to another group
 
-```
-$ USE_SSH=true yarn deploy
-```
+We use [CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) to ensure the relevant owner approves a change before it can be merged.
+
+### Deployment
 
-Not using SSH:
+The default branch of the repository is automatically built and deployed as a GitHub Pages site, using GitHub Actions. The deployment and test workflows are in [`.github/workflows/`](.github/workflows/).
 
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
+## Contributing
 
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+Pull requeststs are welcome! See [CONTRIBUTING.md](./CONTRIBUTING.md) for details on how to run the site locally and make changes.