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.json

When 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-01

Runbook 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 release

What this demonstrates:

• ADR metadata for lifecycle tracking
• Runbook owner, backup, drill date
• IDL filename or package version aligned to release

Deep Dive

Document Types

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

FAQs

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.