Skip to content

docs: plain-prose pass over README - #95

Merged
lesnik512 merged 1 commit into
mainfrom
docs/prose-pass
Oct 3, 2026
Merged

lesnik512 merged 1 commit into
mainfrom
docs/prose-pass

Conversation

@lesnik512

Copy link
Copy Markdown
Member

Prose pass over README.md, the only user-facing Markdown in this repo (no mkdocs site; docs/ holds ADRs and agent notes, which are out of scope). Code blocks, inline code, link targets and the pyproject description are unchanged.

What changed

  • Em dashes in prose: 25 -> 0. Replaced with commas, colons, semicolons, parentheses or a sentence split.
  • Bold run-in labels: 8 -> 0 (AsgiFastStream note, "Tuning", "Must be outermost", "Fix", "These raise...", "Still unguarded", and the two bold-led bullets under Limitations > Other). Rewritten as plain sentences.
  • Numbered "How it works" list with bold labels turned into ### subsections (Message dispatch, Concurrency control, Offset committing, Rebalance handling, Shutdown).
  • Decorative bold inside sentences removed (not, outer, before, after, first): 6 instances.
  • Headings to sentence case: Quick start, Core concepts, API reference, How it works.
  • Smaller fixes: dropped a duplicated "other policies pass through untouched" clause in Quick start, "simply passes through" -> "passes through", "restore unbounded buffering" -> "allow unbounded buffering" (version-history wording).

Anchors

  • The Core concepts link "Rebalance handling" pointed at #how-it-works; it now points at the new #rebalance-handling subsection.
  • "See Quick Start for usage examples" is now a link to #quick-start.
  • No other file in the repo links to the renamed headings.

Left on purpose

  • Three **not honoured** cells in the control-signals table: the following paragraph refers to the rows "marked not honoured", so the marking carries meaning.
  • The emoji footer headings (PyPI, License) match the org-wide README footer.

Verification

  • just lint-ci: passes.
  • Tests: 209 passed against a throwaway Redpanda container on port 39192 (KAFKA_BOOTSTRAP_SERVERS=localhost:39192 uv run --no-sync pytest), container removed afterwards.

@lesnik512
lesnik512 merged commit 49a7e5c into main Oct 3, 2026
11 checks passed
@lesnik512
lesnik512 deleted the docs/prose-pass branch October 3, 2026 14:30
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