Skip to content

Add writing guidance to AGENTS.md and apply it to docs - #5990

Open
danielmarbach wants to merge 3 commits into
masterfrom
agents-md-writing-guidance
Open

danielmarbach wants to merge 3 commits into
masterfrom
agents-md-writing-guidance

Conversation

@danielmarbach

Copy link
Copy Markdown
Contributor

Updates AGENTS.md to the current engineering context template and applies its new Writing section to the pages under docs/.

The template now has a Writing section that applies to pull request descriptions, commit messages, docs/, ADRs, and code comments. It asks for the main point first, no restated or inflated text, short active sentences, one term per concept, and no invented facts. Commit subjects are short imperative summaries without emoji or type prefixes. Code comments explain only what the code cannot state.

How the docs revision was made

An agent revised the docs using only the Writing section of AGENTS.md, and the diff was reviewed by hand. Edits that removed information were reverted, such as contrasts that correct a likely assumption, history that explains a current default, and "should" in guidelines rewritten as a statement. Those cases led to the clarifications in the last commit.

The docs commit also fixes typos, two broken link syntaxes, and British spellings, and converts headings to sentence case. Heading changes are case-only where other pages link to them, so anchors still resolve.

Commits

Review the commits separately. AGENTS.md is a verbatim copy of the template, and the docs commit changes wording, not meaning.

  • 14f3939 Add writing guidance to AGENTS.md
  • a5161db Apply AGENTS.md writing guidance to docs
  • 2c74e12 Clarify AGENTS.md writing rules

Found but not changed

  • packaging.md says RavenDBServer.zip is used by ServiceControl and Monitoring instances. deployment.md and the project file comments say the primary and Audit instances.
  • packaging.md names the zip folder zip, and deployment.md names it zips. The repository has zip/.
  • error-ingestion-design.md says the instance "runs a single ingestion loop today", which conflicts with the concurrent writers and --error-ingestion-only hosts in ingestion-pipeline.md.
  • data-versioning-design.md refers to "the reflection test above", but no test is described above it.
  • Broken links: testing.md links packaging.md#assembly-mismatches (the anchor is #assembly-version-mismatches) and /docs/test/ghcr-tag (the folder is test-ghcr-tag). forward-headers-testing.md links testing-architecture.md, which does not exist.

@danielmarbach

Copy link
Copy Markdown
Contributor Author

// cc @johnsimons @rbev @warwickschroeder

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant