Frontend Documentation Standards

Documentation improves maintainability — frontend systems should remain understandable beyond their original authors.

01 — Purpose

Systems outlive authors

Documentation improves maintainability and onboarding — frontend systems should remain understandable beyond their original authors.

Code explains what happens; documentation explains why, how to extend, and what not to touch. Without it, onboarding slows, decisions get re-litigated, and standards drift within weeks.

This site is itself documentation — see standards, patterns, and checklists for the model.

02 — Principles

Documentation is part of the frontend system

Architecture docs, component guidance, standards, and onboarding support.

  • architecture documentation — layers, folders, build, and deployment overview
  • component guidance — purpose, props, states, accessibility notes
  • standards documentation — HTML, CSS, JS, accessibility expectations
  • onboarding support — first-week tasks, local setup, where to ask questions

03 — Practice

Good documentation standards

Keep docs close to code; update them in the same PR when behaviour changes.

  • document ADRs or decision logs for non-obvious choices — why Astro, why LSCSS
  • link components to patterns and checklists — see component ownership
  • include “when to use / when not to use” for shared UI
  • maintain a changelog or migration notes for breaking component API changes
  • review docs in PR checklist — same gate as tests for shared systems

04 — Avoid

Documentation debt

Outdated docs are worse than none — they mislead confidently.

  • outdated docs — README still describes the old build tool
  • undocumented decisions — nobody knows why the folder structure exists
  • hidden workflows — deploy and release steps only in one person’s head
  • docs divorced from repo — Confluence pages nobody updates after merge
  • auto-generated API dumps with no prose — reference without guidance

05 — Close

Docs ship with features

If the PR changes behaviour, it updates documentation.

Treat documentation as a deliverable for shared components and architecture changes. A feature is not done until the next developer can use it without a walkthrough.

See component ownership, release readiness checklist, and principles.