Skip to content

Contributing to the Evospin / dropbet doc portal

The authoring workflow for this portal. Sibling document: docs/STYLE.md, which covers voice, headings, code references, and diagram conventions. This file covers process — when to update vs branch, how to mark in-flight content, customer-review gates, and CI integration.

When to update the working copy vs branch the docs

The working copy at docs/ is the latest doc release in flight on master. It is mutable and continuously updated. Past releases are pinned via annotated git tags (v1.0, v1.1, …) — see README.md for the versioning model.

Decision tree:

  1. Typo / link fix / clarification — edit working copy directly. No release bump.
  2. New section / new doc / structural improvement that doesn't break external links — edit working copy directly. Will roll up into the next minor release.
  3. Renaming a top-level path / removing a customer-cited path / changing a glossary term — open a branch, propose the change in a PR, get sign-off (see "Customer-facing review gate" below). Land it just before a minor or major release so the migration note in changelog.md is written once.
  4. Backporting a fix to a tagged release — git tags are immutable. Fixes go into the working copy and inherit forward via the next tag. The only exception is a critical fact correction that needs to land at an older tag; in that case create v<X.Y>.<patch> (e.g. v1.0.1) and log under Backport in changelog.md.

Marking in-flight content

Three markers are recognised across the portal. Doc CI (docs/ci/) enforces these mechanically via tools/docs/find-tbd.sh.

{{TBD}} — known gap

Use when a fact is not yet known, but the slot for it exists. Examples: a placeholder version number, an unfilled key in a matrix, a date that depends on a future release.

- Performance ramp final p95: `{{TBD: pending phase 4 capture}}`

{{TBD}} markers are scanned by CI and reported. A {{TBD}} is acceptable in a release — it is honest. What is not acceptable is silently leaving a wrong fact in place because a {{TBD}} would look unfinished.

> **Status: draft** callout — work-in-progress doc

Use as the first line under the H1 when an entire document is in draft and should not yet be cited externally.

# Failover runbook

> **Status: draft.** Last updated 2026-04-25 by Alice. Pending review by SRE.

…body…

CI flags drafts present at release-tag time. The release maintainer either signs them off (promoting to final) or strips them before tagging.

> **Status: customer-facing — review required** — gated by sales/legal

Use when a doc is intended for external sharing and has not yet been reviewed. Lifts to Status: customer-facing — approved YYYY-MM-DD by <reviewer> after sign-off.

Customer-facing review gate

Documents under business/, delivery/, handover/ (parts of), and the sanitized layer of security/ are by default customer-shareable. Any change to these — including additions to existing sections — requires:

  1. A diff review by the business / delivery owner for accuracy and tone.
  2. A separate diff review by the security review when the change touches anything in the security layer (sanitized or otherwise).
  3. The reviewer's name + sign-off date is recorded in the doc's Status: callout.

Engineering-only docs (under engineering/, runbooks/, recipes/, adr/, data-model/, architecture/, flows/, plus all internal-layer security docs) skip this gate.

If you're not sure which side a doc falls on: customer-cited paths (those linked from docs/README.md under "Three reading tracks → Business" or "→ Delivery") are customer-facing.

Authoring conventions

  • Use the STYLE guide for voice, heading levels, code references, diagrams.
  • Always cite file:line for source-tree pointers; never citation-by-name.
  • Prefer one fact per bullet — "BullMQ runs on Redis (cache instance, port 6379)" is one bullet, not three.
  • Use Mermaid for diagrams; supply a fallback table.
  • Add new content into existing files where the topic already lives, rather than creating a new file. New files require an update to the relevant track README and to docs/README.md.
  • Cross-link aggressively. A doc with no inbound links is invisible.

Doc CI integration

The CI suite at docs/ci/ (forward-pointer) and tools/docs/ (scripts) is live as of v1.0:

Check Failure mode Severity
Markdown lint (mdlint) Headings, link syntax, fenced-code blocks malformed Block
Internal link checker Relative link points at a missing file or anchor Block
{{TBD}} scanner Reports count + locations; does not block but tracked release-over-release Warn
Terminology lint Forbidden terms (e.g., "world-class", marketing voice) per STYLE §1 Block in customer-facing docs, warn elsewhere
Draft scanner Documents with Status: draft cannot be in a tagged release Block at tag time, warn during normal development

Each rule's enforcement file is in tools/docs/ — see the per-script reference at tools/docs/README.md. The CI workflow at .github/workflows/docs-ci.yml runs every check on every PR.

How to add a new doc

  1. Decide which directory it lives in (track-shaped: business/, delivery/, engineering/; or cross-cutting: api-reference/, architecture/, security/, etc.).
  2. Add the file with the right Status: callout if it's draft.
  3. Update the relevant track README to link the new file in reading order.
  4. Add a one-line link from docs/README.md if it's a top-level cross-cutting concern.
  5. Add to the glossary.md if it introduces new domain terminology.
  6. Mention the addition in changelog.md under the next pending release.

How to release a doc version

The full release process is in README.md → "Release process". Short form:

$EDITOR docs/versions/changelog.md          # add v1.1 entry
git add docs/versions/changelog.md
git commit -m "docs(versions): release v1.1"
git tag -a v1.1 -m "Doc release v1.1"
git push origin master v1.1

The changelog entry and the tag land together. Do not push the tag before the changelog edit is on master.

Backports across tagged releases

By default tagged releases are immutable history. The two exceptions:

  1. Wrong-fact correction — a fact in a tagged release is materially incorrect and customers are citing it. Create a vX.Y.Z patch tag pointing at a fix commit; log under Backport in changelog.md.
  2. Security disclosure delta — a security finding's customer-disclosure layer changed (e.g. something previously internal must now appear in the customer-shareable layer). Allowed via a patch tag; coordinate with security review.

All other backports are rejected. The right answer is to land the change in the working copy and let it roll up into the next minor tag.

Pull request checklist

Building & linting the site

The docs render as a MkDocs Material site with two build targets:

python3 -m pip install -r requirements.txt   # one-time toolchain install
./build-docs.sh team      # full internal site        -> site/
./build-docs.sh client    # pre-sale / client site     -> site-client/
./lint-docs.sh            # both builds --strict, zero warnings (the gate)

./lint-docs.sh is the linter: it builds both the client and team sites with --strict, so any broken link, bad nav entry, or unrecognized reference fails it. Cross-repo references (into the ebit-platform monorepo, ebit-api, etc.) must be absolute GitHub URLs — relative ../../ paths escape the docs tree and fail the strict build. Run it before every docs commit.

Enable it as a pre-commit hook once per clone:

git config core.hooksPath .githooks

The hook only fires when docs files are staged, and skips with a hint if the mkdocs toolchain isn't installed (CI is the hard gate). The client site excludes all internal material (security findings, weakness register, incidents, runbooks, perf, eng internals) — keep client-facing pages free of links into those tracks, or the strict client build will fail.

Before requesting review on a docs PR:

  • [ ] ./lint-docs.sh passes (both client and team are strict-clean).
  • [ ] Style guide observed (voice, headings, code references, diagrams). STYLE.md.
  • [ ] No marketing voice in customer-facing files.
  • [ ] All file references use path:line.
  • [ ] All Mermaid diagrams have a fallback table.
  • [ ] Every assertion either cites source or carries a {{TBD}} marker.
  • [ ] New file? Linked from the relevant track README and (if cross-cutting) docs/README.md.
  • [ ] If touching customer-facing content, business/security review attached.
  • [ ] Doc CI is green (when CI lands; until then, manual review).