Skip to content

docs: apply writing guidelines across the docs site - #87

Merged
roziscoding merged 3 commits into
mainfrom
docs/writing-pass
Aug 19, 2026
Merged

docs: apply writing guidelines across the docs site#87
roziscoding merged 3 commits into
mainfrom
docs/writing-pass

Conversation

@roziscoding

Copy link
Copy Markdown
Owner

Applies the writing conventions from the global CLAUDE.md to every docs page except guide/quick-links.md, which was already written to them in #86.

No behavioural or factual changes, prose only.

What changed

  • Em dashes used as pauses or pivots replaced with commas, colons, semicolons, or a second sentence (the bulk of the diff, ~60 instances).
  • Bullet label separators normalised from - **Label** — text to - **Label**: text.
  • UI references are now bold+italic with ASCII arrows: ***Settings -> Downloads***, ***Settings -> General -> API Key***, ***Live*** / ***Reconnecting...***.
  • Rule-of-three phrasing removed: the index hero tagline, the what-is-jack intro, and the unlink description in troubleshooting.
  • Counting before a list dropped: "three usual causes" and "two on-disk outcomes" now just introduce their lists.
  • Preamble and filler cut: "First, a decoding tip:", "That's it —".
  • Wh-word heading renamed: 3. Serving — being a peer to others -> 3. Serving as a peer to others.
  • Unicode punctuation (, , , smart quotes) removed from prose, including the mounts table in getting-started.

Not changed

  • Mermaid blocks in how-it-works.md keep and inside message labels, since -> there collides with mermaid's own arrow syntax.
  • [operationId].paths.ts keeps the em dash in its generated page titles, where it separates title from section rather than acting as a pause.

Renamed headings keep their existing anchors (verified in the built HTML), and bun run build passes.

@greptile-apps

greptile-apps Bot commented Aug 19, 2026

Copy link
Copy Markdown
Contributor

Greptile Summary

The PR applies the repository’s writing conventions across the documentation without changing application behavior.

  • Replaces Unicode punctuation and em-dash constructions with the prescribed ASCII punctuation and sentence structures.
  • Standardizes UI references, list labels, headings, and concise phrasing.
  • Adds the writing conventions to AGENTS.md.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Reviews (2): Last reviewed commit: "docs: add writing guidelines to AGENTS.m..." | Re-trigger Greptile

@roziscoding
roziscoding merged commit 5400239 into main Aug 19, 2026
10 checks passed
@roziscoding
roziscoding deleted the docs/writing-pass branch August 19, 2026 21:09
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