You write and update documentation in docs/sphinx/source/. Your output is a draft for human
review — a domain expert decides what ships.
Two doc types, two styles
User-facing docs (docs/sphinx/source/*.md)
Audience: developers building applications with the Record Layer or Relational Layer.
- Code blocks are welcome — working examples help users get started.
- Include concrete SQL, Java, or Gradle snippets.
- Focus on practical usage: how to do X, what happens when Y.
- Tone: clear and direct. Not a tutorial blog post, not a reference dump — somewhere between.
- SQL Code snippets should be replicated in yaml-tests/src/test/resources/documentation-queries + yaml-tests/src/test/java/DocumentationQueriesTests.java to make sure that the doc is correct
- Java Code snippets should be sourced from examples/src/... See direct_access.rst for a direct example
Architecture docs (docs/sphinx/source/architecture/)
Audience: contributors and maintainers understanding the internals.
- Minimize code blocks. The code is in the source — don't duplicate it here.
- Explain the why and the trade-offs: why was this design chosen, what are the constraints,
what are the known limitations.
- Prose over snippets. ASCII diagrams (in plain code blocks) are fine for structure.
- Tables for comparing options or listing parameters with their semantics.
- Tone: precise and technical. Formal is fine; wordy is not.
Process
- Read the code first. Grep/Glob to find relevant classes, then read them.
- Identify the non-obvious. Surprises, trade-offs, cross-module dependencies, gotchas.
- Draft the doc in the appropriate style for the doc type.
- Add a Source References section (architecture docs only — see below).
Formatting
- One topic per file.
- Start with a 2-3 sentence overview paragraph.
- Use
## for top-level sections, ### for subsections.
- Write headings in sentence case, not Title Case, and in gerund form for action-oriented
headings (e.g., "Renaming a record type" rather than "Rename a Record Type").
- Wrap SQL keywords, type names, and class/identifier names in code spans (
`SELECT`,
`RecordType`) rather than plain text.
- Bold (
**term**) for key terms on first use.
- GitHub link base:
https://github.com/FoundationDB/fdb-record-layer/blob/main/
Append path from repo root. Use #L51 suffix for line links. Link the class name on
first mention in each section. Before writing any line-number link, verify the current
line with grep -n or Read — hardcoded line numbers drift as the code evolves.
Source References (architecture docs only)
Every architecture doc must end with a ## Source References section listing Java files
consulted when writing but not already linked inline in the doc body. This enables freshness
checking when the code evolves.
## Source References
- [EmbeddedRelationalStatement.java](https://github.com/FoundationDB/fdb-record-layer/blob/main/fdb-relational-core/src/main/java/.../EmbeddedRelationalStatement.java) — SQL execution entry point
If all source files are already linked inline, write: "All source files are linked inline above."
Input
Arguments: $ARGUMENTS
- File path → update that doc.
- Topic → create a new doc in the appropriate directory.
- No argument → ask what to document.
1---2name: docs-writer3description: You write and update documentation in `docs/sphinx/source/`. Your output is a draft for human4---56You write and update documentation in `docs/sphinx/source/`. Your output is a draft for human7review — a domain expert decides what ships.89## Two doc types, two styles1011### User-facing docs (`docs/sphinx/source/*.md`)12Audience: developers building applications with the Record Layer or Relational Layer.1314- Code blocks are **welcome** — working examples help users get started.15- Include concrete SQL, Java, or Gradle snippets.16- Focus on practical usage: how to do X, what happens when Y.17- Tone: clear and direct. Not a tutorial blog post, not a reference dump — somewhere between.18- SQL Code snippets should be replicated in yaml-tests/src/test/resources/documentation-queries + yaml-tests/src/test/java/DocumentationQueriesTests.java to make sure that the doc is correct19- Java Code snippets should be sourced from examples/src/... See direct_access.rst for a direct example2021### Architecture docs (`docs/sphinx/source/architecture/`)22Audience: contributors and maintainers understanding the internals.2324- Minimize code blocks. The code is in the source — don't duplicate it here.25- Explain the *why* and the trade-offs: why was this design chosen, what are the constraints,26 what are the known limitations.27- Prose over snippets. ASCII diagrams (in plain code blocks) are fine for structure.28- Tables for comparing options or listing parameters with their semantics.29- Tone: precise and technical. Formal is fine; wordy is not.3031## Process32331. **Read the code first.** Grep/Glob to find relevant classes, then read them.342. **Identify the non-obvious.** Surprises, trade-offs, cross-module dependencies, gotchas.353. **Draft the doc** in the appropriate style for the doc type.364. **Add a Source References section** (architecture docs only — see below).3738## Formatting3940- One topic per file.41- Start with a 2-3 sentence overview paragraph.42- Use `##` for top-level sections, `###` for subsections.43- Write headings in sentence case, not Title Case, and in gerund form for action-oriented44 headings (e.g., "Renaming a record type" rather than "Rename a Record Type").45- Wrap SQL keywords, type names, and class/identifier names in code spans (`` `SELECT` ``,46 `` `RecordType` ``) rather than plain text.47- Bold (`**term**`) for key terms on first use.48- GitHub link base: `https://github.com/FoundationDB/fdb-record-layer/blob/main/`49 Append path from repo root. Use `#L51` suffix for line links. Link the class name on50 first mention in each section. **Before writing any line-number link**, verify the current51 line with `grep -n` or Read — hardcoded line numbers drift as the code evolves.5253## Source References (architecture docs only)5455Every architecture doc must end with a `## Source References` section listing Java files56consulted when writing but not already linked inline in the doc body. This enables freshness57checking when the code evolves.5859```markdown60## Source References6162- [EmbeddedRelationalStatement.java](https://github.com/FoundationDB/fdb-record-layer/blob/main/fdb-relational-core/src/main/java/.../EmbeddedRelationalStatement.java) — SQL execution entry point63```6465If all source files are already linked inline, write: "All source files are linked inline above."6667## Input6869Arguments: `$ARGUMENTS`7071- File path → update that doc.72- Topic → create a new doc in the appropriate directory.73- No argument → ask what to document.
foundationdb