Skip to content

Documentation Style Guide

Style, voice, and terminology rules for the Evospin / dropbet docs portal. Every doc under docs/ follows this guide. Doc CI (ci/) enforces the mechanical parts.

1. Voice

  • Declarative, present tense. "The OTel Collector forwards spans to Jaeger." Not "will forward" or "should forward".
  • Second person sparingly. Use "you" only in onboarding, recipes, and runbooks where the reader is an actor. Reference docs (architecture, API reference, glossary) are written in the third person.
  • No marketing voice. Customer-facing docs (business/, delivery/) state capabilities factually. No "world-class", "seamless", "enterprise-grade".
  • Jargon policy. Customer-facing docs may use jargon only after defining it once in-doc or linking to glossary.md. Engineering docs assume engineering literacy and do not redefine "BullMQ", "OTel", "p95", etc.
  • No hedging. "May", "might", "should probably" are signals to either dig deeper or mark {{TBD}}. If a fact is uncertain, mark it; if it is certain, state it directly.

2. Heading conventions

  • One H1 per file, at the very top. The H1 is the document title.
  • H2 for major sections. H3 for subsections. H4 is allowed only inside reference tables of contents — avoid otherwise.
  • ATX style only (# Heading), never Setext (Heading\n=====).
  • Sentence case for headings ("Reading order recommendations"), not Title Case.
  • No trailing # characters; no manual numbering ("1. Voice" in this doc is the exception — it's a numbered top-level outline that mirrors the spec).

3. Code references

Use file_path:line_number format for every pointer into the source tree. The path is relative to the relevant repo root (ebit-api/, ebit-fe/, ebit-admin-fe/).

  • Good: apps/api/src/auth/auth.service.ts:42
  • Good: libs/_prisma/src/schema/api.prisma:625
  • Bad: the auth service (ungreppable)
  • Bad: /home/ubuntu/ebit/ebit-api/apps/api/... (machine-local absolute path)

Inline backticks for filenames (`bet.service.ts`) when the line number is not relevant or when grouping multiple references in prose. Always include the line number when citing a specific function, constant, or schema field.

4. Diagrams

  • Mermaid only. No PNG/SVG checked in unless it's a screenshot of an external UI (e.g., Jaeger).
  • Keep each diagram ≤30 nodes. Split into multiple diagrams if larger.
  • Always include a fallback table below each diagram describing the same nodes/edges, for accessibility and for readers whose Markdown viewer doesn't render Mermaid.
  • Edge styling convention: solid = active in production, dashed = stubbed/disabled, red label = trace-propagation gap.
  • Sequence diagrams use participant aliases; service-map diagrams use graph LR.

5. Cross-references

  • Relative paths only. From docs/architecture/service-map.md to docs/glossary.md, write ../glossary.md. Never /home/ubuntu/ebit/docs/glossary.md and never https://gitlab.example.com/.../glossary.md.
  • Always end relative directory links with /. [runbooks/](runbooks/) not [runbooks](runbooks). The trailing slash is the signal that it's a directory, not a file.
  • Anchor links use the auto-generated GitHub-style slug: lowercase, spaces → hyphens, punctuation stripped. Verify by hovering the rendered heading.
  • Every cross-reference must resolve. Doc CI runs a link checker over the portal; broken links fail the build.

6. Terminology — canonical list

Use these spellings exactly. Doc CI flags deviations.

Canonical Notes
Evospin The platform / product brand name. Capital E, one word. Use in prose, headings, and rendered site titles. Not a rename of the code-level identifiers below — repo names, services, env vars, DB names, and the ebit Doppler workspace keep their existing ebit-* / ebit spelling until the underlying resources are renamed.
ebit-api The NestJS monorepo. Lowercase e, hyphenated. Five apps inside it: api, rt, bj, bo, speed-roulette.
ebit-fe The player-facing Next.js app. Branded "dropbet" — when speaking to end-users, say "dropbet"; when speaking to developers, say "ebit-fe".
ebit-admin-fe The internal admin Vite + React 19 SPA. Never abbreviated to "admin-fe" in headings; inline OK.
dropbet The customer-facing brand name (lowercase). Used in player UI copy and customer-facing docs.
NestJS Capital N, capital JS. Not "Nest.js" or "nestjs".
Next.js With the dot. Not "NextJS" or "Next js".
OTel OpenTelemetry, always abbreviated in body text. Spell out only on first mention in a customer-facing doc.
OpenTelemetry Collector The collector binary specifically — capitalize "Collector" when naming it.
spanmetrics One word, lowercase. The OTel Collector connector that derives RED metrics from spans.
BullMQ Capital B, capital MQ. The Redis-backed job queue. Not "Bull MQ", "bullmq", or "BullMq".
RabbitMQ The broker that runs in compose but is wired only to the stubbed Fast Track module.
Doppler Secrets management — proper noun, always capitalized.
SUT System Under Test — used in performance docs. Always uppercase.
loadgen The load generator VM. Lowercase, one word.
k6 Lowercase k. The load-testing tool.
stepped ramp / soak / spike k6 profile names. Always lowercase, two words for "stepped ramp".
p95, p99, p50 Lowercase p, no period, no space. Not "P95" or "p95th".
ws Lowercase, abbreviated. Use "websocket" (one word, lowercase) in prose; ws only as a port-name or short tag.
Postgres Not "PostgreSQL" in body text (use "Postgres"); the formal name is acceptable in security/compliance docs.
Redis Capital R. We run two instances: cache Redis (6379) and bot Redis (6380).
Jaeger / Loki / Grafana / Prometheus Proper nouns, capitalized.
DBC "DropBet Coin", the platform currency. Always uppercase.
2FA Not "two-factor auth" in headings; spell out on first mention in customer-facing docs.
{{TBD}} The placeholder marker. Doc CI scans for this exact string.

When you find another recurring term while writing, add it here rather than coining a variant.

7. TBD markers

Use {{TBD}} (double curly braces) for any unfinished section, unknown number, or pending decision. Doc CI scans the portal for this string and reports counts per file.

  • {{TBD}} — bare marker; OK for tables and short fields.
  • {{TBD: who owns the staging Sentry org?}} — annotated marker; preferred when context helps the next writer.
  • Avoid TODO, FIXME, ???, <unknown> — none of those are scanned.

When a {{TBD}} is resolved, remove the marker and the surrounding hedge wording in the same edit.

8. Customer-safe vs internal

The portal has two visibility tiers. Default is customer-safe; internal-only material is opted in by location and banner.

Customer-safe (no banner needed): - Top-level docs except those under */internal/ - All of business/, delivery/, handover/, api-reference/, architecture/, flows/, recipes/, runbooks/, data-model/, onboarding/, glossary.md, env-reference.md (template values only), observability.md, performance-testing.md, performance-test-report.md, e2e-trace-demo.md, api/, versions/

Internal-only (banner required): - Anything under engineering/internal/ or security/internal/ - Doppler tokens, real production secrets, customer-list-revealing material - Vendor contractual details, internal headcount, payroll, infra cost numbers

Internal-only docs must start with this banner immediately after the H1. Either form is acceptable:

> **INTERNAL ONLY** — do not share outside the ebit team. Contains operational detail, secrets, or vendor information.

> 🔒 **INTERNAL ONLY.** <one-line reason — e.g., cites file paths and env vars not appropriate for external distribution>.

The lock-emoji form is preferred for visual scannability when many internal docs sit side-by-side; the plain form is preferred when the banner is followed immediately by structured content. Doc CI accepts both.

The security register splits along the same line: security/ is the customer-safe layer (categories, severities, mitigation status); security/internal/ (when present) carries the unredacted finding bodies.

9. File and directory naming

  • Filenames: lowercase, hyphenated, .md extension. bet-place.md, not BetPlace.md or bet_place.md.
  • Directories: lowercase, hyphenated, no trailing slash in the directory name itself.
  • READMEs: every non-trivial directory has a README.md that lists its contents and a one-line "what's inside" per file.
  • Dates: ISO 8601 (2026-04-25), not 04/25/2026 or 25 April 2026.

10. Validation

Before merging a doc PR:

# Markdown syntax / link check
ls docs/ci/   # see ci/README.md for the configured tooling

# {{TBD}} census
grep -rn '{{TBD}}' docs/ | wc -l

# Mermaid block parity (every ```mermaid has a closing ```)
grep -c '```' docs/**/*.md   # should be even

When in doubt about voice, terminology, or layout, grep an existing doc that's already merged and follow its lead. The glossary, the architecture index, and the api-reference README are the load-bearing examples.