docs and cleanup

README.md

@@ -9,7 +9,7 @@ documentation websites.
 
 The `docs.deno.com` website is hosted on [Deno Deploy](https://deno.com/deploy),
 where it is fronted by a [Hono](https://hono.dev/) web server that handles
-redirects and other dynamic content requests.
+redirects and other dynamic content requests as they become necessary.
 
 ## Local development
 
@@ -38,11 +38,11 @@ To test the generated static site in a production configuration, run:
 npm run build
 ```
 
-This will generate a static site to the `build` folder locally. Change into this
-directory, and run the Deno server bundled there with:
+This will generate a static site to the `build` folder locally. To test the
+production server (through the actual Deno / Hono server), run this command:
 
 ```
-deno run --allow-net --allow-read server.ts
+npm run serve
 ```
 
 This will start a Deno server on [localhost:8000](http://localhost:8000), where
@@ -55,7 +55,9 @@ and need to clean Docusaurus' generated assets. You can do this by running:
 npm run clear
 ```
 
-This will solve most errors you encounter while refactoring the site.
+This will solve most errors you encounter while refactoring the site. Static
+assets will be rebuilt from scratch the next time you run `npm run build` or
+`npm start`.
 
 ## Editing content
 
@@ -88,8 +90,8 @@ more details.
 
 Philosophically, we want to maintain as few discrete versions of the
 documentation as possible. This will reduce confusion for users (reduce the
-number of versions they need to think about) and help us maintain the docs by
-keeping our build times faster.
+number of versions they need to think about), improve search indexing, and help
+us maintain the docs by keeping our build times faster.
 
 In general, we should only version the documentation **when we want to
 concurrently maintain several versions of the docs**, like for major/LTS
@@ -111,6 +113,9 @@ It may occasionally be desirable to dynamically include the current Deno CLI or
 standard library version in content or code samples. We can accomplish this
 using the `replacements.json` file at the root of this repository.
 
+Any values you would like to change once, and then have appear dynamically in a
+number of generated files, should be included in `replacements.json`.
+
 In code samples (fenced with backticks), you can include a `$` character,
 followed by the replacement variable name, directly within the code sample. When
 the markdown is transformed, the current version number will be replaced within
@@ -129,6 +134,42 @@ import Replacement from "@site/src/components/Replacement";
 The current CLI version is **<Replacement for="CLI_VERSION"/>**.
 ```
 
+## Server-side code and redirects
+
+The Deno code that serves the site in production is in the `src-deno` folder.
+When the `npm run build` command is executed for a production Docusaurus build,
+it also copies the contents of the `src-deno` folder (unchanged) into the
+resulting `build` folder, which will be our project root for Deno Deploy.
+
+Right now, there is just a very thin [Hono](https://hono.dev/) server sitting on
+top of the static assets generated by Docusaurus. The only interesting job the
+Hono app has right now is handling redirects, of which there are several from
+the previous Deno doc sites.
+
+To add a redirect, open `src-deno/redirects.ts` and configure a new route in the
+default exported function. The default status code of `301` should be sufficient
+for most cases.
+
+## New release process for Deno runtime
+
+Let's say that a new minor release is ready for Deno, with CLI version `1.99`
+and standard library version `0.999.0`. Here's how I would recommend approaching
+the docs for this release right now.
+
+- Create a feature branch for the release, like `release_1_99` or similar
+- Update `replacements.json` with the upcoming CLI and standard lib versions
+- As the release is developed, add docs changes to this branch
+- When the release is ready, submit a PR to the `main` branch from this feature
+  branch
+- When the branch is merged, create a `v1.99` tag from the new `main` branch
+
+For patch releases, I would recommend simply submitting pull requests to the
+`main` branch with relevant updates to `replacements.json` as required.
+
+If we decide we'd like to have "canary" docs for upcoming versions, we can
+discuss how to make that possible with
+[Docusaurus versions](https://docusaurus.io/docs/versioning).
+
 ## Deployment
 
 The `docs.deno.com` site is updated with every push to the `main` branch, which