Skip to main content

Writing for this handbook

The rules​

  1. Generic only. No product names, client names, AWS account IDs, real hostnames, bucket names, IP addresses, people's names, or any secret. Use example-app, api.example.com, 123456789012, example-bucket.
  2. Diagram before text. Juniors read pictures faster than paragraphs. Use Mermaid (fenced block with mermaid). One diagram per idea.
  3. Short sentences. Plain English. Explain a term the first time you use it.
  4. Say why. Every rule needs the reason, or people delete it later.
  5. Record mistakes. If something cost real time or caused an outage, add it to the page's Mistakes we made section: what happened, why, what to do instead.
  6. Date the law. Anything legal or regulatory gets an "as of" date and a link to the official source. Laws change.
  7. No emojis.

Page template​

---
sidebar_position: 3
title: Short title
---

# Short title

One or two sentences: what this is and when you need it.

## How it works

(mermaid diagram)

Short explanation of the diagram.

## How to build it

Steps, code, config.

## Rules

:::danger[Rule]
The rule. Why.
:::

## Mistakes we made

- **What happened.** Why. What to do instead.

## Checklist

- [ ] Item

Give an admonition its title in brackets: :::danger[Rule]. The older :::danger Rule form does not render on this site and shows as plain text.

Run it locally​

npm install
npm start

Opens on http://localhost:3000. npm run build fails on broken links, so run it before you push.

Rule

Do not deploy this site to GitHub Pages. A Pages site is public even when the repo is private. If we host it, it goes behind a login or a client certificate.

Last updated on