Technical Reference

A stable lookup document designed for repeated return visits. Optimized for scanning over reading. The reader arrives with a specific question; the format serves that question.

Technical Reference

Technical reference is not written to be read start to finish. It is written to be consulted. The reader arrives with a specific question - what are the parameters for this function? what does this error mean? what are the valid values for this field? - and the reference document should answer that question in the fewest possible steps. Every structural decision in a technical reference document serves the returning reader, not the first-time reader. Headers are navigation. Tables beat prose for structured data. Examples beat explanation.

The authority of a technical reference comes from its precision and stability. Precision means every statement is accurate and complete for its scope - not approximately right, not rounded for readability. Stability means the document changes only when the underlying system changes, not to improve the prose. A reader who bookmarks a section of a reference document is trusting that section to remain findable and accurate. That trust is the contract the format creates.

Technical reference is distinct from tutorials and how-to guides. A tutorial walks a newcomer through a concept; a how-to guide walks a practitioner through a task. A reference document assumes the reader already knows what they want to do and needs the exact specification to do it. Mixing tutorial prose into a reference document - adding context, motivation, and explanation that the experienced reader will skip - is the most common way reference documents fail the readers who rely on them most.

Canonical template

# [Component / Function / Concept Name]

[One sentence: what this is and what it does. No background.]

## Syntax / Signature

[Exact syntax or function signature]

## Parameters / Fields / Options
| Name | Type | Required | Description |
|------|------|----------|-------------|
| [name] | [type] | [yes/no] | [concise description] |

## Returns / Output
[What is returned or produced - type and structure]

## Examples
```[language]
[Working minimal example]

[Optional: second example showing edge case or variation]

Notes / Constraints

• [Important limitation, gotcha, or version note]

See Also

• [Related component or concept] - [link or cross-reference]

### When to use

Technical reference belongs on any API, library, CLI tool, or configuration schema that practitioners consult repeatedly. Use it when the reader is experienced with the domain and arrives with a specific question, when precision and completeness matter more than approachability, and when the document needs to stay stable and findable across software versions.

### When not to use

Reference format is wrong for introducing someone to a concept for the first time, guiding a practitioner step by step through a task, or explaining the reasoning behind a design decision. It is also wrong for non-technical stakeholders who need context, and for one-time documentation that will not be consulted again.

### Pairs well with

`technical-writer`, `pragmatic-architect`, `matter-of-fact`, `instructional`, `diataxis-explanation`

### Often confused with

**diataxis-explanation**: A Diataxis explanation document teaches conceptual understanding - it is oriented toward learning and can include motivation, analogy, and context. A technical reference document is oriented toward lookup - it assumes understanding and prioritizes precision and scannability over explanation.

**how-to-tutorial**: A how-to guide walks a practitioner through a specific task with sequential steps toward a defined goal. A technical reference document is a stable specification that a practitioner consults while doing a task - it does not guide; it answers.

## Instruction

```text
Write as technical reference documentation. Optimize for scanning, not reading start to finish.
Every section should be findable via its header. Use tables for structured data (parameters,
options, fields). Lead each entry with a one-sentence definition - no background or motivation.
Include at least one working code example. State constraints and limitations as explicit notes,
not as caveats buried in prose. Do not explain why the system works this way - state precisely
how it works. Assume the reader already knows what they want to do and needs the specification
to do it.

Template

See the Technical Reference template.

Related

Pairs well with

Technical Writer, Pragmatic Architect, Matter of Fact, Instructional, Diataxis Explanation

Avoid with

Columnist, Pastoral, Warm, Playful, Narrative Case Study

Often confused with

Diataxis Explanation, How-To Tutorial

Examples

Should we adopt async-first standups?

Platform Standup Format Reference

Applies to: eng-platform team (11 engineers, 4 timezones) Channel: #team-standup Status: Trial - effective 2026-05-19 through 2026-06-19 Owner: Maya Chen (EM Platform)

1. Posting template

Post once per workday in #team-standup. Copy the pinned message and fill in.

*Shipped*
- <item>

*In progress*
- <item>

*Blocked / at risk*
- <item, with @mention of who can resolve>

If a section is empty, write - none. Do not omit the heading.

2. Field definitions

Field	Includes	Excludes
Shipped	Work merged, deployed, or otherwise complete in the last 24h	Work in review; planning; meetings attended
In progress	Current focus through your next workday	Backlog; speculative work; “thinking about X”
Blocked / at risk	Anything where someone else’s input changes your day, plus things trending late	Vents; status with no ask; non-actionable FYI

A blocker requires three things: what is blocked, who can unblock, when you need it. @user, can you review #4412 today? is a blocker. Reviews are slow. is not.

3. Timing rules

Rule	Value
Post by	10:00 your local time
On-call triage by	09:00 Pacific
Blocker first-response SLA	30 min during business hours of the resolver
Backfill window for missed post	Same day, until 17:00 local

If you will not be at a keyboard before 10am local (early meeting, school run, travel), post the previous evening with a tomorrow: prefix on In progress.

4. Blocker escalation

day 0 (post)        - @mention the resolver in your update
+4 business hours   - on-call engineer nudges the resolver in-channel
+1 business day     - on-call escalates to the resolver's manager
+2 business days    - escalates to Maya

Mark a blocker resolved by editing your original post or replying in-thread with resolved: and the outcome. Do not delete the line - the searchable record is part of the point.

5. Edge cases

PTO

Post one line on your last working day: OOO <date range>, back <date>. Coverage: @user. Do not post during PTO.

On-call

On-call engineer posts as normal plus a fourth line: *On-call:* responding to pages, async post may be late. On-call days do not count against participation metrics.

Partial week / holidays

Post on the days you work. On a public holiday for your locale, skip without notice.

No update to give

Post anyway. Shipped: none. In progress: <thing>. Blocked: none. Silence is harder to interpret than a thin update.

Heads-down / deep work day

Post as normal. The five minutes it takes is the price of the team knowing where you are. If you genuinely cannot context-switch, post the night before.

Sensitive items

If a blocker involves a person issue or anything confidential, post Blocked: DMing @maya and handle in DM. Do not name the person in-channel.

6. Metrics tracked

Pulled weekly by Priya from #team-standup history.

Metric	Definition	Target
Participation rate	Posts / engineers / workday	>= 9/11
Blocker response time	Time from post to first substantive reply	< 30 min business hours
Stale blockers	Blockers open > 2 business days	0

7. Related

• Trial proposal: docs/proposals/async-standup-trial.md
• Thursday working session charter: docs/eng-platform/thursday-session.md
• ADR-0014: Adopt async-first standup format
• Day-15 pulse and day-30 review: calendar invites from Maya

How to start a morning routine

Morning Routine: Module Reference

A reference for the four composable modules of the standard weekday morning routine. Each module has defined inputs, outputs, timing, and failure modes. Modules execute sequentially in the order listed unless otherwise noted.

1. Overview

The routine is decomposed into four modules executed between wake time (T+0) and end-of-window (T+60 minutes). Total elapsed time is approximately 45 minutes; the remaining 15 minutes is buffer for transitions and interruptions.

1.1 Module summary

#	Module	Duration	Window	Required
1	Water	1 min	T+0 to T+5	Yes
2	Light	10 min	T+5 to T+20	Yes
3	Movement	15 min	T+20 to T+40	Yes
4	Planning	10 min	T+40 to T+55	Yes

2. Module: Water

2.1 Purpose

Establish the first physical action of the day as a chosen one. Secondary benefit: rehydration after 7-8 hours without intake.

2.2 Inputs

Input	Specification
Volume	8 oz (240 ml)
Temperature	Room temperature
Location	Bedside or kitchen, prepared the night before
Preconditions	Eyes open, feet on floor

2.3 Outputs

• One glass consumed
• Transition signal to module 2

2.4 Failure modes

• No water prepared: Default to tap water in kitchen. Do not skip.
• Forgot until after phone-check: Routine has already failed at module 0 (phone discipline). Reset tomorrow.

3. Module: Light

3.1 Purpose

Provide bright-light exposure within 30 minutes of waking to support circadian alignment and morning alertness.

3.2 Inputs

Input	Specification
Duration	10 minutes
Light source	Outdoor daylight preferred; large window acceptable
Posture	Standing or seated; eyes open
Concurrent activity	Optional: water sips, slow breathing

3.3 Outputs

• 10 minutes of light exposure completed
• Transition signal to module 3

3.4 Fallback variants

Condition	Fallback
Rain or cold	Largest window in house, blinds fully open
Pre-dawn (winter)	Bright indoor lighting + 10,000 lux lamp if available
Travel	Hotel window or hallway window

4. Module: Movement

4.1 Purpose

Raise core body temperature, mobilize joints after sleep, and generate a modest cardiovascular signal to wake the system.

4.2 Inputs

Input	Specification
Duration	15 minutes
Intensity	Low to moderate (talk pace)
Modality	Walk, stretching sequence, or bodyweight
Equipment	None required

4.3 Outputs

• 15 minutes of movement logged (mental note, not tracked)
• Transition signal to module 4

4.4 Failure modes

• Injury or illness: Substitute with 10 minutes of stretching or gentle mobility only.
• Time pressure (running late): Compress to 5 minutes; do not skip entirely.

5. Module: Planning

5.1 Purpose

Convert vague morning intentions into a concrete written shortlist before any digital tool is opened.

5.2 Inputs

Input	Specification
Duration	10 minutes (hard cap)
Tool	Paper notebook, pen
Location	Desk, kitchen table, or stationary surface
Prerequisites	Modules 1-3 completed

5.3 Outputs

Output	Format
Today’s top three priorities	Three bullet lines
Today’s protection list	What to defend time against
Today’s drop list	What to explicitly not do

5.4 Constraints

• No phone, laptop, or tablet during this module
• Do not extend past 10 minutes; route weekly planning to Sunday evening block
• Do not use this module to process email or messages

6. Sequencing rules

• Modules execute in numerical order (1 -> 2 -> 3 -> 4).
• Modules 2 and 3 MAY be combined (walking outside satisfies both light and movement). When combined, allocate the maximum of the two durations.
• An interrupted module resumes at the next module after the interruption ends; the interrupted module is not retried.

7. End state

At T+60, the routine is complete. Phone re-enters the workflow. Daily shortlist is in hand. Work day begins at T+150 (9:00am).

8. Variants

Variant	Modules	Total time	Use case
Standard	1, 2, 3, 4	45 min	Weekday at home
Compressed	1, 4	6 min	Travel days
Recovery	1, 2, 4	21 min	Illness or injury
Weekend (TBD)	Not yet specified	-	Future spec

How to choose between Postgres and DynamoDB for a new service

Lattice Notify Datastore Selection Matrix

The reference rubric the architecture review board (ARB) uses to evaluate a new datastore for a new service. Used in the Wednesday 2026-05-13 review for the notification service (Postgres vs DynamoDB).

Signature

evaluate_datastore(
    candidate: DatastoreOption,
    workload: WorkloadProfile,
    team: TeamProfile,
    horizon_months: int,
) -> EvaluationResult

Inputs

Name	Type	Required	Description
candidate	DatastoreOption	yes	The datastore being evaluated (e.g. postgres-extended, dynamodb-new)
workload	WorkloadProfile	yes	Read/write rates, access pattern, consistency requirements, peak/average ratio
team	TeamProfile	yes	Headcount, on-call rotation size, existing operational knowledge per datastore
horizon_months	int	yes	Planning horizon for the evaluation (typically 12 for service-level decisions)

Evaluation Dimensions

Dimension	Weight	Postgres (notification svc)	DynamoDB (notification svc)
Access-pattern fit	0.15	Adequate; needs schema design + indexes	Strong; native fit for point-lookup writes
Throughput at launch (500K events/day)	0.10	Strong; well within current cluster headroom	Strong
Throughput at 12-month upside (5M events/day)	0.10	Adequate with partitioning + queue tuning	Strong; scales without intervention
Team operational knowledge	0.25	Strong; 3 years of production experience	Weak; one personal-project spike
On-call rotation surface area	0.20	No change	Doubles (new runbook, monitoring, alerts)
Cross-database query needs	0.10	Strong; joins to existing user/account data are SQL	Weak; cross-store joins become application code
Recovery cost if wrong	0.05	3-6 weeks; predictable	3-6 weeks; less predictable
Vendor lock-in / portability	0.05	Open source; high portability	AWS-only; high lock-in

Outputs

The evaluation produces a weighted score per candidate and a recommendation. The recommendation is not the highest score; it is the highest score whose downside scenarios are recoverable given the team profile.

EvaluationResult(
    candidate="postgres-extended",
    weighted_score=0.79,
    recommendation="adopt",
    revisit_threshold="5M events/day sustained",
    rationale_doc="adr/0023-postgres-notification-service.md",
)

Examples

# Notification service evaluation, 2026-05-13
workload:
  writes_per_day: 500_000
  upside_writes_per_day: 5_000_000
  read_pattern: point_lookup_by_user
  consistency: read_your_writes
team:
  backend_engineers: 8
  on_call_rotation: 4
  postgres_ops_years: 3
  dynamodb_ops_years: 0
horizon_months: 12
result:
  recommendation: postgres-extended
  revisit_threshold: 5M events/day sustained

# Counterexample: a future workload where the recommendation would flip
workload:
  writes_per_day: 50_000_000
  upside_writes_per_day: 200_000_000
  read_pattern: point_lookup_by_user
  consistency: eventual
team:
  backend_engineers: 40
  on_call_rotation: 12
  postgres_ops_years: 5
  dynamodb_ops_years: 2
horizon_months: 18
result:
  recommendation: dynamodb-new

Notes / Constraints

• The Team Operational Knowledge dimension is the highest-weighted single dimension by design. The ARB raised this weight from 0.15 to 0.25 in 2025 after two incidents where a technically-superior datastore was adopted by a team that could not operate it under load.
• Revisit thresholds are mandatory for any recommendation; an evaluation without a threshold is rejected on submission.
• The matrix is for service-level datastore decisions only. Application-level cache choices use a separate rubric (see caches-selection-matrix.md).
• Version 2.3 of this rubric (current) added the Cross-database query needs dimension after the 2024 search service decision.

See Also

• ADR-0023: Postgres for notification service - the canonical worked example of this matrix
• WorkloadProfile schema specification - schemas/workload-profile.yaml
• ARB charter and decision process - governance/arb-charter.md
• Lattice Notify capacity planning guide - ops/capacity-planning.md

Appears in diff-pairs

• technical-reference vs devotional-entry (varies format)
• technical-reference vs readme (varies format)