Skip to content

docs: polish the README - #42

Merged
owenthcarey merged 1 commit into
mainfrom
docs/polish-readme
Oct 3, 2026
Merged

owenthcarey merged 1 commit into
mainfrom
docs/polish-readme

Conversation

@owenthcarey

Copy link
Copy Markdown
Contributor

Summary

Restructures README.md to be easier to scan and more polished, without changing what it says about WeaveC.

  • Centred header with a tagline, the existing badges plus a Releases badge, and navigation links.
  • A short pitch built around the four strategies (prove, check, guard, record), then a Highlights list.
  • A new How it works section with a table of the six ledger outcomes and how weavec-cc enforces each; annotations get their own subsection.
  • Using it as the compiler split into Checks, Guards and Analysis without building.
  • Modes and options: fixes a stray blank line that split the bullet list; the run-on "other flags" sentence becomes a table, with a link to the CLI reference.
  • Guarantees: (S)/(N)/(T)/(G)/(V) wording kept, now labelled; the six assumptions as a table; the limits of (G) as a list.
  • Installing a release as numbered steps; a new Documentation index; the Code of Conduct linked from Contributing.

Design notes

  • Every code example and every block of compiler output is byte-for-byte unchanged (one comment in the build block: # Everyone → # All platforms).
  • Removed "The first release creates CHANGELOG.md…", which is stale now that CHANGELOG.md exists; the README links to it instead.
  • The ## Building heading is kept because CONTRIBUTING.md links to README.md#building.

Test plan

  • Diffed all fenced blocks against the previous README: identical apart from the comment above
  • Every relative link resolves to an existing file
  • Rendered page checked on GitHub

Documentation only; no code, tests or formats change.

Restructure the README for scanning: a centred header with a tagline and
release badge, highlights, an outcomes table, labelled guarantee clauses
and assumptions, an options table, numbered release install steps and a
documentation index. Code examples and compiler output are unchanged.
@owenthcarey
owenthcarey merged commit 6047863 into main Oct 3, 2026
8 of 9 checks passed
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