Repository navigation
Add writing guidance to AGENTS.md and apply it to docs - #5990
Open
danielmarbach wants to merge 3 commits into
Open
danielmarbach wants to merge 3 commits into
danielmarbach wants to merge 3 commits into
Conversation
Contributor
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Updates
AGENTS.mdto the current engineering context template and applies its new Writing section to the pages underdocs/.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.mdis a verbatim copy of the template, and the docs commit changes wording, not meaning.Found but not changed
packaging.mdsaysRavenDBServer.zipis used by ServiceControl and Monitoring instances.deployment.mdand the project file comments say the primary and Audit instances.packaging.mdnames the zip folderzip, anddeployment.mdnames itzips. The repository haszip/.error-ingestion-design.mdsays the instance "runs a single ingestion loop today", which conflicts with the concurrent writers and--error-ingestion-onlyhosts iningestion-pipeline.md.data-versioning-design.mdrefers to "the reflection test above", but no test is described above it.testing.mdlinkspackaging.md#assembly-mismatches(the anchor is#assembly-version-mismatches) and/docs/test/ghcr-tag(the folder istest-ghcr-tag).forward-headers-testing.mdlinkstesting-architecture.md, which does not exist.