Documentation Conventions
Solana systems fail when docs live only in Slack: upgrade steps, PDA seed docs, and incident runbooks must live in version control beside programs and clients. These conventions align engineering docs with this SME guide format.
Recipe
Quick-reference recipe card - copy-paste ready.
docs/
adr/ 0001-title.md
runbooks/ deploy-mainnet.md, incident-pause.md
specs/ feature specs
packages/idl/
lending.json version in filename or package.jsonWhen to reach for this:
- Setting up new monorepo
- Audit documentation request list
- Contributing to this knowledge base
- Post-incident "we had no runbook" action item
Working Example
ADR header
# ADR 0007: Mainnet RPC provider selection
Status: Accepted | Supersedes: none | Review: 2026-12-01Runbook header
# Runbook: deploy-mainnet.md
Owner: @alice | Backup: @bob | Last drill: 2026-05-15
## Prerequisites
- Squads signer 2-of-3 available
- CI artifact hash from release tag
## Steps
1. ...
## Rollback
solana program deploy --program-id ... ./artifacts/previous.so
## Verification
solana-verify get-program-hash ...IDL publish
anchor idl build -o packages/idl/lending-v2.4.0.json
# package.json "version": "2.4.0" matches program releaseWhat this demonstrates:
- ADR metadata for lifecycle tracking
- Runbook owner, backup, drill date
- IDL filename or package version aligned to release
Deep Dive
Document Types
| Type | Location | Audience |
|---|---|---|
| ADR | docs/adr/ | Engineering, auditors |
| Runbook | docs/runbooks/ | On-call |
| Spec | docs/specs/ | PM + eng |
| IDL | packages/idl/ | Client codegen |
| SME Guide | site/solana/ | Developers |
SME Page Footer
Every authored guide page ends with stack versions blockquote per site pipeline.
Gotchas
- Wiki runbooks - Stale during incident. Fix: Git only; PR review for changes.
- IDL not committed - Client builds drift. Fix: CI publish on tag.
- ADR edited in place - History lost. Fix: Supersede with new number.
- Explorer screenshots only - Not reproducible. Fix: CLI commands in runbook.
- Undocumented PDA seeds - Client derivation bugs. Fix: Rustdoc on seed constants.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
| Notion for specs | PM preference | Sole runbook store |
| Auto-generated Rustdoc | Public crates | Runbooks |
| OpenAPI for off-chain API | REST services | On-chain IDL |
FAQs
ADR vs RFC?
RFC proposes; accepted RFC becomes ADR or links to it.
Runbook drill evidence?
Date + ticket link in runbook header after quarterly drill.
Spanish docs?
English canonical in repo; translate-es overlays per site pipeline.
Who approves doc PRs?
Runbooks: ops owner; ADRs: tech lead; guide: any senior.
IDL breaking change?
Major semver; migration section in release notes.
Diagrams?
Mermaid in git; export PNG optional for slides.
Secret in runbook?
Never; reference vault path only.
Audit doc package?
ADR index + architecture diagram + IDL + threat model.
Stale page policy?
Review-by date in ADR; guide regen on stack version bump.
Contributor guide link?
See contribution guidelines page in same section.
Related
- Architecture Decision Records (ADRs) - ADR process
- Contribution Guidelines - who updates what
- Coding & Program Standards - code conventions
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.