docs: write the docs and readme in plainer prose #521

Merged

dries merged 2 commits from docs/plain-prose into main

2026-08-20 09:25:53 +02:00

dries commented

2026-08-20 00:52:53 +02:00

Owner

Editing pass over the readme and all five docs chapters. No behaviour changes.

Removed every em dash (~120 of them). They became periods, commas, or a colon before a definition list; numeric en-dash ranges became hyphens or "to".
Rewrote **Label** — restatement bullets as **Label.** New detail., so the bold lead-in introduces content instead of repeating itself.
Headings to sentence case in workflows.md, releases.md, architecture.md, profiling.md.
Passive to active where the actor was known ("responses are size-limited" → "ocman size-limits responses it reads from upstream").
Split the densest paragraphs: the MCP splitting sequence is now five steps, and multi-remote's "How it works (one paragraph)" is two paragraphs under a heading that doesn't apologise for its length.
Dropped the ✅/⏸ status emoji from the profiling task table.

Two factual fixes fell out of the pass, both matching AGENTS.md:

mcp.md said the composed prompt includes git diff --stat; it's ocman's own per-file change summary, which deliberately isn't that shape.
contributing.md pointed at internal/server/static/ for the embedded bundle; it's internal/webui/static/. Also removed the stale "180+ Go tests / 81 frontend tests" counts.

make docs-build succeeds and all internal links still resolve.

Editing pass over the readme and all five docs chapters. No behaviour changes. - Removed every em dash (~120 of them). They became periods, commas, or a colon before a definition list; numeric en-dash ranges became hyphens or "to". - Rewrote `**Label** — restatement` bullets as `**Label.** New detail.`, so the bold lead-in introduces content instead of repeating itself. - Headings to sentence case in `workflows.md`, `releases.md`, `architecture.md`, `profiling.md`. - Passive to active where the actor was known ("responses are size-limited" → "ocman size-limits responses it reads from upstream"). - Split the densest paragraphs: the MCP splitting sequence is now five steps, and multi-remote's "How it works (one paragraph)" is two paragraphs under a heading that doesn't apologise for its length. - Dropped the ✅/⏸ status emoji from the profiling task table. Two factual fixes fell out of the pass, both matching AGENTS.md: - `mcp.md` said the composed prompt includes `git diff --stat`; it's ocman's own per-file change summary, which deliberately isn't that shape. - `contributing.md` pointed at `internal/server/static/` for the embedded bundle; it's `internal/webui/static/`. Also removed the stale "180+ Go tests / 81 frontend tests" counts. `make docs-build` succeeds and all internal links still resolve.

dries added 1 commit

2026-08-20 00:52:53 +02:00

docs: write the docs and readme in plainer prose

CI / Frontend (pull_request) Successful in 7m57s

Details

CI / Playwright E2E (pull_request) Successful in 9m4s

Details

CI / Backend (pull_request) Successful in 9m32s

Details

CI / Coverage Results (pull_request) Successful in 27s

Details

CI / Build (pull_request) Successful in 4m53s

Details

CI / Semantic Tag (pull_request) Successful in 6s

Details

e2580ef0ae

Strip the em dashes, bold-label restatements, title-case headings and
passive constructions that had accumulated across the readme and every
docs chapter. Split the densest paragraphs and drop the status emoji in
the profiling task table.

Two facts corrected on the way through: the MCP prompt carries ocman's
own per-file change summary rather than `git diff --stat`, and the
embedded assets live in `internal/webui/static/`. Also removes the stale
test counts from the contributing page.

forgejo-actions commented

2026-08-20 01:02:52 +02:00

Coverage ratchet: ✅ pass

Suite	Baseline	This PR	Δ
frontend	71.22%	71.22%	+0.00	✅
go	81.30%	81.30%	+0.00	✅

Tolerance: -0.1%. Baseline stored on gh-pages.

### Coverage ratchet: ✅ pass | Suite | Baseline | This PR | Δ | | |---|---|---|---|---| | frontend | 71.22% | 71.22% | +0.00 | ✅ | | go | 81.30% | 81.30% | +0.00 | ✅ | _Tolerance: -0.1%. Baseline stored on `gh-pages`._

dries added 1 commit

2026-08-20 02:47:29 +02:00

docs: fix stale session-status and MCP web-UI port claims

CI / Frontend (pull_request) Successful in 7m53s

Details

CI / Backend (pull_request) Successful in 10m17s

Details

CI / Build (pull_request) Successful in 4m17s

Details

CI / Playwright E2E (pull_request) Successful in 8m11s

Details

CI / Coverage Results (pull_request) Successful in 28s