Skip to content

Writing

Use this when you start a draft. Goal: complexity made simple. A teammate should get it on the first read.

Voice

  • Casual and concise. Write like you’re explaining it over coffee, not presenting to a steering committee.
  • NZ English. Organise, behaviour, licence (noun), initialise.
  • No corporate lingo. Skip “leverage”, “synergy”, “best-of-breed”, “journey”, “empower”.
  • Prefer “you” and “we”. Short paragraphs. One idea per section.
  • No “Who Benefits” sections. The reader can decide if it’s for them.

Where it goes

If the piece is…Put it in…
A pattern or principle that will still matter in three yearsConcepts — Patterns or Principles
Steps, playbooks, “do this then check that”Guides — Observability, CI/CD, Containers
Scripts, CLIs, glue you’d keep in a team repoGuides / Tooling
Opinion, trade-offs, trend takes, dated adviceInsights — Trends or Strategy

Tag by provider, discipline, and audience. Three to five tags is plenty.

Skeletal framework 

The mess          ← open with lived pain (1–3 sentences)
The idea / take   ← name the approach; plain language
[body]            ← section-specific (below)
Check it worked   ← optional; Guides almost always
Gotchas           ← what bites; what I'd skip
Related           ← optional links; end when the point is made

Concepts body

When it fits → How to apply it

Guides body

Before you start → Steps → Check it worked

Insights body

What’s going on → What I’d do → What I’d skip

Insights use The take when the opinion is the hook.

Tooling body

Same as Guides, leaner: mess → steps/script → check → gotchas.

Scaffold a draft 

hugo new content concepts/patterns/my-pattern.md
hugo new content guides/observability/my-playbook.md
hugo new content --kind tooling guides/tooling/my-script.md
hugo new content insights/strategy/my-take.md

Reference posts

Last updated on • Steve Rackham