Skip to content

Writing guide

This guide keeps articles consistent in quality and tone. It is deliberately short; use judgement over checklists, except for the pre-publication checklist at the end, which is mandatory.

Structure and argument

  • Begin with the problem or practical context. Readers should know within two paragraphs why the topic matters and whether the article is for them.
  • State the central position clearly, early, in plain language. An article should be summarizable in one sentence.
  • Explain trade-offs honestly. Every recommendation has contexts where it is wrong. Name them. An article that admits its limits is more credible, not less.
  • Do not present preferences as universal rules. "We default to X because…" is honest; "you must always X" is rarely true.
  • Separate facts from opinions. Facts get citations; opinions get reasoning. Clearly label experimental results, benchmarks, and personal opinions as such.
  • Use the article template as a starting point, but drop headings that would make the writing unnatural.

Style

  • Prefer plain English. Use technical terms where they are precise, not where they decorate.
  • Use concrete examples — real commands, real configuration, real failure modes. Verify that every command and code sample actually works.
  • Keep paragraphs reasonably short. One idea per paragraph.
  • Use diagrams only when they clarify the argument. A diagram that restates the prose is noise. Use Mermaid so diagrams stay text and diff cleanly.
  • Cite authoritative sources and link to primary documentation (official docs, specifications, original papers) rather than secondhand blog posts.

Confidentiality and safety

These rules are non-negotiable:

  • Do not publish client-confidential information of any kind.
  • Do not name clients, internal systems, or private incidents without explicit written permission.
  • Generalize real-world lessons into reusable guidance — the lesson is publishable; the engagement it came from is not.
  • Remove all credentials, API keys, internal URLs, tenant IDs, subscription IDs, account IDs, hostnames, and any other identifying infrastructure detail. Use obviously fake placeholders (00000000-0000-0000-0000-000000000000, contoso.example.com) in examples.
  • Do not fabricate benchmarks, adoption claims, or project history.

AI-assisted writing

AI tools may be used in drafting and editing, with the same standard applied as to any draft: the named author is fully responsible for every claim. Before publication, review AI-assisted text specifically for:

  • Confident statements that are subtly wrong or unverifiable
  • Invented references, version numbers, configuration options, or APIs
  • Generic filler that adds length without adding information

If a command, flag, or behaviour cannot be verified by running it or by primary documentation, it does not ship.

Pre-publication checklist

  • [ ] The problem and central position are clear in the first two paragraphs
  • [ ] Trade-offs and limits of the position are stated
  • [ ] Facts are cited; opinions and experimental results are labelled as such
  • [ ] All commands, code samples, and configuration have been executed or verified against primary documentation
  • [ ] All internal and external links resolve
  • [ ] Mermaid diagrams render correctly in a local preview (mkdocs serve)
  • [ ] No client names, confidential details, credentials, tenant/subscription IDs, internal URLs, or identifying infrastructure information
  • [ ] No fabricated benchmarks, claims, or history
  • [ ] Front-matter metadata is complete: title, description, date, authors, categories (from the allowed list), tags
  • [ ] AI-assisted passages have been fact-checked and edited for voice
  • [ ] mkdocs build --strict passes locally