From a8af427c8c7f7bd674555d49541d3ed5e40761d4 Mon Sep 17 00:00:00 2001 From: Frederic BIDON Date: Fri, 21 Aug 2026 20:46:32 +0200 Subject: [PATCH] doc: fix doc style Signed-off-by: Frederic BIDON --- .claude/rules/technical-writing.md | 67 ++++++++++++++++++++++++++ docs/doc-site/usage/core/validation.md | 2 +- docs/examples/auth/bearerjwt/main.go | 2 +- docs/examples/client/intro/main.go | 2 +- docs/examples/server/security/main.go | 2 +- 5 files changed, 71 insertions(+), 4 deletions(-) create mode 100644 .claude/rules/technical-writing.md diff --git a/.claude/rules/technical-writing.md b/.claude/rules/technical-writing.md new file mode 100644 index 00000000..3f0ae364 --- /dev/null +++ b/.claude/rules/technical-writing.md @@ -0,0 +1,67 @@ +--- +paths: + - "**/*.go" + - "**/*.md" +--- + +# Technical writing style (go-openapi) + +Applies to every committed comment, commit message, README and doc-site page. + +The standard is Ernest Gowers, *Plain Words*: **be short, be simple, be human.** +His worked example is the whole rule: + + DON'T Was this the realisation of an anticipated liability? + DO Did you expect to have to do this? + +The abstract nouns carry no information; the concrete verb carries all of it. + +## Two tests + +**The grep test.** Does the sentence contain something a reader can search for — an +identifier, a file, a flag, an error, a number with a unit? Prose that names nothing has +described the code without pointing at it. + +**The quotability test.** A sentence that would survive being quoted on its own is too +pleased with itself. Rewrite it until it merely sounds true. + +## Never define by inversion + +The worst and most frequent fault. A copula whose subject or predicate is a wh-clause +promises a definition and delivers a metaphor. Both directions are banned: + + DON'T Coverage is what says which templates a suite never reaches. + DON'T What is lost is the doc comment. + DO Coverage records which templates the suite never executed. + DO A synthesized type loses its doc comment. + +The rewrite is mechanical: find the verb hiding inside the wh-clause and make it the main +verb of the sentence. + +`which is why` pointing back at a fact just stated is legitimate, and rationed — one per +comment is plenty. + +## The rest + +- **Name the thing.** `WithRoots`, not "the option that scopes a repository". Name the + error, the file, the flag, the upstream package, the constant. +- **Statement, not aphorism.** State mechanism and effect. Never close a paragraph on a + maxim: the reflex lands hardest on a closing sentence. +- **Keep a subject.** "New returns an error if the source is unreadable", not "What a + source leaves out is settled where it is declared". +- **Plain verbs.** add, fix, return, parse, reject, cap, prune, record. Code does not say, + judge, grant, refuse, know, mean to, or reach for. `report` is fine when something + genuinely reports. +- **Keep the numbers.** Sizes with units, counts, ratios, advisory ids. `286 -> 178 KiB`, + `GHSA-v2xp-g8xf-22pf`. Dropping them for a smoother sentence loses information. +- **Be human.** Address the reader where there is advice: "Use `WithRoot` to confine local + loading." Admit the awkward thing rather than smoothing it over. + +## Self-check + + # definition by inversion, both directions + grep -rnE '\b(is|are) (what|where) [a-z]' --include='*.go' --include='*.md' . + grep -rnE '(^|\. )What [a-z][a-z ,-]{3,50} (is|are) ' --include='*.go' --include='*.md' . + +Subtract the legitimate `which/that/this/it is what` before judging the first one. +Neither grep is a verdict — they find one fault out of six. The others need reading. diff --git a/docs/doc-site/usage/core/validation.md b/docs/doc-site/usage/core/validation.md index 5ee7894d..c7fdc22a 100644 --- a/docs/doc-site/usage/core/validation.md +++ b/docs/doc-site/usage/core/validation.md @@ -79,4 +79,4 @@ named formats (`date-time`, `uuid`, `email`, …) into the validator. You rarely build one by hand — the server's `*Context` and the client `Runtime` each carry one and pass it down. To register a custom format (`x-go-type` style), call `strfmt.Default.Add(...)` once at startup; the -default registry is what both sides use unless overridden. +both sides use the default registry unless overridden. diff --git a/docs/examples/auth/bearerjwt/main.go b/docs/examples/auth/bearerjwt/main.go index 37e175dd..237b5764 100644 --- a/docs/examples/auth/bearerjwt/main.go +++ b/docs/examples/auth/bearerjwt/main.go @@ -27,7 +27,7 @@ import ( // doc stands in for a real `*loads.Document` loaded via `loads.Spec`. var doc *loads.Document -// principal is what the authenticator returns on success. The runtime +// principal is the value the authenticator returns on success. The runtime // stores it in the request context for the operation handler to use. type principal struct { Subject string diff --git a/docs/examples/client/intro/main.go b/docs/examples/client/intro/main.go index 688aae19..61567c36 100644 --- a/docs/examples/client/intro/main.go +++ b/docs/examples/client/intro/main.go @@ -6,7 +6,7 @@ // cannot rot silently. // // `go run .` exercises the demo (the SubmitContext call is expected to -// fail against the placeholder host — wiring is what we demonstrate). +// fail against the placeholder host — this demonstrates the wiring). package main import ( diff --git a/docs/examples/server/security/main.go b/docs/examples/server/security/main.go index 5a0c5a3d..874389d9 100644 --- a/docs/examples/server/security/main.go +++ b/docs/examples/server/security/main.go @@ -186,7 +186,7 @@ func registerAuthorized() { func readPrincipal(r *http.Request) { if r == nil { // readPrincipal is invoked from main() for compile coverage; the - // snippet body itself is what gets rendered into the docs. + // snippet body itself is rendered into the docs. return }