Reference Document #

Scalable engineering teams aren’t just strong in architecture and code — they’re also strong in shared understanding. When every team member has a different definition of what a “critical bug” is, what “P1” means, or how to name an endpoint correctly, every discussion risks wasting time aligning on understanding that should already be settled. The reference document is the answer to that problem: the official reference defining standards, terminology, and classifications used consistently by the whole team — across roles, across sprints, across time.

What Is a Reference Document? #

A reference document is a normative document defining what something means in the team’s context. It isn’t technical documentation explaining how a system works, isn’t a process guide explaining work steps, and isn’t an RFC discussing architecture decisions. A reference document answers one simple question that is often a source of conflict:

“When we say X, what do we actually mean?”

The main characteristics distinguishing reference documents from other document types:

Reference documents sit among other documents as the foundation ensuring all of them use the same terminology.

flowchart TD
    RD["Reference Document\nstandards & terminology"]
    RFC["RFC\narchitecture decisions"]
    PG["Process Guide\nhow things work"]
    REL["Release Document\nwhat changed"]
    
    RD -->|"defines terminology for"| RFC
    RD -->|"defines standards for"| PG
    RD -->|"defines classifications for"| REL

Why Are Reference Documents Important? #

Eliminating the Same Repeated Discussions #

Without reference documents, the same questions arise every time a new case appears:

// Scenario without a reference document
Bug triage meeting:
  QA: "I'm marking this High severity because users can't check out"
  Developer: "But there's a workaround, it should be Medium"
  PM: "This must be P0 because revenue is impacted"
  → 20 minutes of discussion, no decision yet
  → The final decision depends on who's the most vocal

// Scenario with a reference document
Bug triage meeting:
  QA: "Checkout fails, no workaround → High severity per the reference"
  PM: "Revenue impact > 10% → P1 priority per the reference"
  → 2 minutes, everyone agrees, moving to the next agenda item

Reducing Team Cognitive Load #

Every decision that doesn’t need to be remade is mental energy left for more meaningful work. Reference documents turn recurring decisions into simple lookups.

Speeding Up Onboarding #

New engineers don’t need to ask basic questions that should already be documented:

// Onboarding without a reference document
New engineer: "When creating a new endpoint, do we use snake_case or camelCase?"
Senior: "Depends... check the existing code"
New engineer: "Service A uses snake_case, service B uses camelCase"
Senior: "Oh right, we're not consistent yet, follow the majority"
→ No clear standard, code becomes increasingly inconsistent

// Onboarding with a reference document
New engineer: opens the Naming Convention Reference
→ "URL paths: kebab-case, JSON bodies: camelCase, DB columns: snake_case"
→ Can start working without depending on anyone

Maintaining Quality Without Adding Technical Complexity #

Reference documents are a quality guardrail that needs no tooling or automation — just documented agreements that everyone follows.

Types of Reference Documents in Engineering Teams #

Bug Severity Level Reference #

Severity defines a bug’s impact on the system and users — independent of how fast it must be fixed.

// How to use the severity reference
Question 1: Is there a practical workaround?
  → No → at least High
  → Yes but impractical → consider High or Medium

Question 2: How many users are affected?
  → All or most users → bump up one level
  → A small subset → keep or bump down one level

Question 3: Is there a risk of data loss or corruption?
  → Yes → Critical, regardless of the number of affected users

Severity is a technical/functional assessment, not a business one. A Medium-severity bug can become P0 priority if the business context requires it — for example, a bug appearing right as a major campaign is running.

Priority Level Reference #

Priority defines the order of work based on business context and impact — not just technical severity.

// Severity vs priority in practice
Bug: The "Export Report" button doesn't work

Severity: High
  → A main feature for the premium merchant segment is unusable
  → No workaround except requesting data manually from CS

Priority: P1 (not P0)
  → Doesn't block transactions or direct revenue
  → But experienced by 200+ active merchants every day
  → Target: fixed this sprint

// A more complex example
Bug: Typo on the About Us page

Severity: Low (no functional impact)
Priority: P3 (done if capacity allows)
→ Severity and priority align for simple cases

Bug: The advanced filter feature doesn't work on mobile

Severity: Medium (workaround exists: use desktop)
Priority: P1 (40% of traffic comes from mobile, a mobile campaign starts this week)
→ Priority higher than Severity due to business context

Naming Convention Reference #

Naming conventions are one of the reference documents with the most direct impact on the codebase. Inconsistent naming isn’t just an aesthetic issue — it increases the cognitive load of every engineer reading the code.

// URL Paths — use kebab-case
✓ GET /api/v1/order-items
✓ POST /api/v1/user-addresses
✗ GET /api/v1/orderItems
✗ GET /api/v1/order_items

// JSON Request/Response Bodies — use camelCase
✓ { "orderId": "...", "paymentMethod": "..." }
✗ { "order_id": "...", "payment_method": "..." }

// Database Tables — use snake_case, plural
✓ orders, order_items, user_addresses
✗ Order, orderItem, UserAddress

// Database Columns — use snake_case
✓ created_at, updated_at, order_status
✗ createdAt, UpdatedAt, orderStatus

// Environment Variables — use SCREAMING_SNAKE_CASE
✓ DATABASE_HOST, REDIS_PORT, JWT_SECRET_KEY
✗ databaseHost, redis_port

// Go / Service Functions — use PascalCase (exported) or camelCase (unexported)
✓ func ProcessPayment()  // exported
✓ func validateInput()   // unexported
✗ func process_payment()

Test Scenario Title Reference #

Inconsistent test scenario titles make test suites hard to maintain and hard to understand when something fails.

// Recommended format: GIVEN-WHEN-THEN or WHEN-THEN
// WHEN <condition> THEN <expected result>

// ✓ Good titles — explicit and self-contained

"WHEN user submits valid email and password THEN user is redirected to dashboard"
"WHEN user submits expired token THEN system returns 401 Unauthorized"
"WHEN cart is empty THEN checkout button is disabled"
"GIVEN user has pending order WHEN payment webhook received THEN order status updated to paid"

// ✗ Bad titles — ambiguous, uninformative when failing

"Test login"          → which login? what condition? what result?
"Login works"         → "works" can't be verified
"Verify checkout"     → verify what?
"Happy path"          → happy path of which flow?

// Additional rules:
✓ Avoid words: "correctly", "properly", "works", "should"
✓ Include a specific condition (input/state)
✓ Include a measurable expected outcome
✓ Use language understandable by non-engineers (for tests demoed to the PO)

Error Classification Reference #

Consistent error classification enables targeted logging, alerting, and retry strategies.

flowchart TD
    E[Error] --> CE{"Client Error\n4xx"}
    E --> BE{Business Error}
    E --> SE{"System Error\n5xx"}
    E --> TE{Transient Error}

    CE --> CE1["400 Bad Request\nInvalid input"]
    CE --> CE2["401 Unauthorized\nMissing/expired token"]
    CE --> CE3["403 Forbidden\nNo access rights"]
    CE --> CE4["404 Not Found\nResource doesn't exist"]

    BE --> BE1["Domain validation failed\ne.g. out of stock"]
    BE --> BE2["Invalid state transition\ne.g. order already paid"]

    SE --> SE1["500 Internal Server Error\nUnhandled exception"]
    SE --> SE2["503 Service Unavailable\nDB/dependency down"]

    TE --> TE1["Timeout\nCan be retried"]
    TE --> TE2["Rate limited\nRetry with backoff"]

API Response Structure Reference #

Defining a consistent response structure across all services prevents frontends from guessing formats and enables uniform error handling.

// ✓ Success Response
{
  "success": true,
  "data": {
    "order_id": "ORD-2026-001",
    "status": "paid"
  },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

// ✓ Error Response
{
  "success": false,
  "error": {
    "code": "PAYMENT_INSUFFICIENT_BALANCE",
    "message": "Insufficient balance to complete the transaction",
    "details": {
      "required": 150000,
      "available": 75000
    }
  }
}

// ✗ Inconsistent formats (anti-pattern)
// Service A:
{ "status": "error", "msg": "not found" }
// Service B:
{ "success": false, "error_message": "User not found", "code": 404 }
// Service C:
{ "data": null, "errors": ["Resource does not exist"] }

Best Practices for Writing Reference Documents #

Prioritize Examples Over Definitions #

Reference documents containing only abstract definitions won’t be used. What makes a document useful is concrete examples that can be directly mapped to real situations.

// ✗ Definition without examples — doesn't help when making decisions

"Critical: A bug that makes the system unusable"

// ✓ Definition with concrete examples — immediately applicable

"Critical: A bug that makes a main feature unusable by
the majority of users, with no practical workaround.
Examples: Login page returns error 500 for all users, payment gateway unresponsive"

Separate Reference from Process #

Reference documents answer what, process guides answer how. Mixing the two makes documents hard to navigate:

// ✗ Mixing reference and process in one document

"High severity is a bug that blocks a main feature.
How to handle a High severity bug:
1. Open a ticket in Jira
2. Assign it to the on-call developer
3. Update the status every 2 hours"

// ✓ Separate into two documents
Severity Level Reference → defines what High, Critical, Medium, Low mean
Bug Handling Process → explains the handling steps per severity

Set an Owner and Review Schedule #

A reference document without an owner goes stale — definitions that no longer match the team’s current condition but nobody dares to change.

// The header every reference document should have
---
Owner: [name or team]
Last Updated: YYYY-MM-DD
Review Schedule: Every quarter or at significant changes
Applies To: The entire engineering team
---

Make It Easy to Find and Access #

A reference document hidden in a folder nobody knows about is effectively nonexistent. Store it somewhere accessible, with an explicit, searchable title:

// ✓ Good folder structure
/docs
  /reference
    severity-bug-level.md
    priority-level.md
    naming-convention.md
    error-classification.md
    api-response-structure.md
    test-scenario-title-convention.md

// ✗ Structure that makes search hard
/docs
  /general
    /standards
      /v2
        misc-standards-final-rev3.md   ← who would ever find this?

Use It Actively in Meetings and Reviews #

A reference document only read once at onboarding isn’t an effective reference document. It must live — actively used during bug triage, code review, and sprint planning:

// Examples of active use in various contexts
Bug Triage:
  "This is High severity because there's no workaround — per our reference definition"

Code Review:
  "This URL should use kebab-case, not camelCase — check the Naming Convention Reference"

Sprint Planning:
  "This story affects the payment flow — we need to define a new error code,
  update the Error Classification Reference before implementation"

Reference Document Anti-Patterns #

// ✗ Reference documents that are too long and academic
Pages 1-5: history and theory of severity classification
Pages 6-10: comparison with other industries
Page 11: the severity table actually needed
→ Nobody reads them — too exhausting for simple information
// ✓ Go straight to the tables and examples, theory in 2-3 intro sentences

// ✗ Reference documents without concrete examples

"Critical: A very severe bug with wide impact"
→ "Very severe" and "wide impact" are still subjective
// ✓ Include real examples from the system being built

// ✗ Reference documents never updated
Last updated 2 years ago
The tech stack has changed, but naming conventions still refer to the old stack
→ The team doesn't trust outdated documents
// ✓ Set a clear owner and review schedule

// ✗ Multiple conflicting reference documents
Bug Severity Reference on Confluence: 4 levels (Critical, High, Medium, Low)
QA Handbook on Notion: 5 levels (Critical, Major, Minor, Trivial, Enhancement)
→ No "single source of truth"
// ✓ One reference per topic, stored in one place

// ✗ Reference documents known only to part of the team

"Oh, that's in the old folder, I forgot where"
→ If not everyone knows where the document is, it effectively doesn't exist
// ✓ Links to all reference documents included in onboarding materials and the README

Healthy Reference Document Checklist #

CONTENT:
  □ Focused on one topic — not mixing reference and process
  □ Every definition includes at least one concrete example
  □ Uses terminology consistent with the codebase and daily communication
  □ No ambiguous definitions that could be interpreted differently

MANAGEMENT:
  □ An owner responsible for keeping the document accurate
  □ A clearly visible "last updated" date
  □ A periodic review schedule (at least once per quarter)
  □ Document changes communicated to all affected teams

ACCESSIBILITY:
  □ Stored somewhere easy to find and search
  □ Explicit, descriptive document titles
  □ Links included in team onboarding materials
  □ Openable and readable in < 5 minutes for common use cases

USAGE:
  □ The team actively references it during bug triage, code review, and technical discussions
  □ If someone asks about a specific definition, the answer is always "check the reference"
  □ If a case isn't covered by the document, the document is updated immediately

Summary #

• Reference documents define “what X means” — not how to do it — separate them from process guides and RFCs.
• Concrete examples are worth more than abstract definitions — “Critical: login down for all users” is more useful than “Critical: wide impact on the system”.
• Severity and priority are two different dimensions — severity measures technical/functional impact, priority measures work order based on business context.
• Consistent naming conventions reduce cognitive load — URLs, JSON, DB columns, and env variables each have conventions that should be documented.
• Test scenario titles must stand on their own — the WHEN-THEN format ensures anyone seeing a failing test immediately understands its context.
• Reference documents must live, not be display pieces — use them actively in bug triage, code review, and onboarding.
• One topic, one document, one source of truth — references fragmented across places are as bad as no reference at all.
• Set an owner and review schedule — documents without owners go stale and lose the team’s trust.

← Previous: Release Document   Next: Syncup →