Technical documentation: [System name]

How to use this template

Each section answers one question, so readers can jump to theirs: Overview and Architecture explain what the system is and why; Setup and Usage are steps to follow; Reference is for looking things up; Troubleshooting is for when something fails. Keep explanation out of the steps and steps out of the explanation.

Delete what doesn't apply, replace every <placeholder> in the code, and update Last reviewed each time you check the document against the system.

Owner

Written for

Covers version

Last reviewed

Questions to

Overview

What it does, for whom, and what it leaves to other systems.

  • Status:

  • Repository:

  • Runs on:

  • Depends on:

  • Used by:

Architecture

How the parts fit together. Add a diagram: a box per component, an arrow per call.

Component

What it does

Built with

Owner

How a request moves through it

Why it's built this way:

Setup

Before you start

Tools and versions, access and who grants it, anything else needed first.

Install and run

  1. Get the code:

    git clone <repository-url>
cd <repository>

  2. Configure:

  3. Start it:

  4. Check that it works:

Usage

One task per heading, starting with a verb. Copy down to the divider.

See an example task

Rotate the API signing key

Do this every 90 days, or at once if a key may have leaked. You need the keys:admin role.

1. Create the new key: keyctl create --service billing-api. It prints the new key's ID.

2. Add the ID to SIGNING_KEYS in the config, before the old one, and deploy. Both keys now verify; the new one signs.

3. After 24 hours, when no token signed with the old key is still valid, remove the old ID and deploy again.

4. Check the Auth dashboard: verification failures should stay at zero.

[Task name]

When you'd do this, and what you need first.

Reference

Configuration

Setting

Default

Required

What it does

Example configuration file:

server:
  port: 8080
database:
  url: <connection string>
  pool_size: 10
log_level: info

Commands, endpoints and limits

  • Commands or endpoints:

  • Limits:

Glossary

Term

What it means in this system

Troubleshooting

Symptom or exact error

Likely cause

Fix

Still stuck? Ask in [channel] with the version, the logs and the steps that led to the problem.