Outward-Facing Documentation — Related Work and Communication Strategy

[soareschen]

AI Overview

This PR turns the CGP knowledge base outward. Until now every section of docs/ looked inward at CGP itself — what a construct is, how a macro expands, how to wire a context. This branch adds the first two sections that look outward: one that compares CGP to the external ideas it resembles, and one that captures how to present CGP to the public. It also rewrites the top-level README.md into a real landing page and adds a construct summary to the reference index. The change is documentation-only: it touches 29 files and adds roughly 2,900 lines under docs/ and README.md, and it does not modify a single crate, macro, or test.

The high-level concepts

The PR introduces two new top-level knowledge-base sections that share one purpose — helping an agent explain CGP to people outside it — but split that purpose along a clean line. The related-work/ section is the depth layer: each document takes one external concept, framework, or language feature and compares CGP to it honestly. The communication-strategy/ section is the audience layer: it generalizes across those comparisons into guidance for writing public material. A reader preparing an article reads a related-work document for the depth of one comparison and a communication-strategy document for the shape of the audience.

The related-work/ section meets a reader on ground they already know before showing where CGP diverges. Its eight documents cover dependency injection, implicit parameters, row polymorphism and extensible data types, algebraic effects and handlers, ML modules and modular implicits, type classes, dynamic dispatch and prototypal inheritance, and reflection and compile-time introspection. Each explains the outside idea faithfully and with citations — this is the one section of the base that cites its sources — states what its users genuinely like and dislike, positions CGP against it, and closes with concrete guidance for a future writer addressing that idea's community. The governing rule is that honesty is the whole value: a document that flatters CGP or strawmans the related work fails, because the readers it ultimately serves are the practitioners most able to see through both.

The communication-strategy/ section teaches the non-technical craft of promoting CGP to a reader who has never studied it. Its thirteen documents span reader profiles, selling points, skepticism and objections, tag lines, key features, technical barriers, attention and engagement, problems solved, positioning, formats and channels, worked example drafts, an audience-facing vocabulary, and a glossary of marketing and developer-relations terms of art. The section is written for a "marketing-naive expert" — someone fluent in CGP but new to marketing, public communication, and developer relations — and its through-line is that honesty is the marketing strategy rather than a constraint on it, because CGP's public audience is unusually able to detect spin. An agent working here is asked to take on the roles of marketing director and developer-relations lead rather than transcribe facts.

The top-level README.md is rewritten from a two-line stub into a full landing page. It now opens with a one-line positioning statement, lists CGP's key features, walks through a #[cgp_fn]-and-#[cgp_component] "quick look" example, and adds installation, an honest "when to use CGP — and when not" section, project status, layout, contributing, and license sections. The version and toolchain markers are refreshed along the way — the Rust floor moves from 1.81+ to 1.89+, the master branch link becomes main, and a prominent note flags that the branch tracks the v0.8.0 pre-release while crates.io still serves the incompatible v0.7.0.

The structural changes

The two new sections follow the knowledge base's established shape, so the structural additions are consistent rather than novel. Each new directory carries a README.md that states its purpose and holds a framed catalog of its documents, and an AGENTS.md that records the authoring rules specific to that section — the obligations every document must meet, the sourcing and citation rules, the synchronization rule as it applies to CGP snippets, and the document structure to follow. This mirrors how the existing sections are governed, so an agent already knows how to read and extend them.

Three existing index documents are updated to register the new sections rather than leave them orphaned. The knowledge-base docs/README.md changes its "five top-level sections" framing to "several," and adds a paragraph describing each of related-work/ and communication-strategy/ and how they relate. The docs/errors/README.md updates its sibling-section list to include related-work/. The docs/reference/README.md gains a new "Summary" section — a grouped, prose tour of every documented construct, ordered from the constructs almost every task needs down to the specialized ones, each group linking to the per-construct document that carries the full detail. These edits keep the base's cross-links complete so no new section is reachable only by guessing its path.

The impacts

Because the PR ships only documentation, its impact is entirely on what agents and human advocates can do with the base, not on any compiled artifact. The following are the concrete effects.

• No code, build, or runtime impact. No crate, macro, trait, or test changes, so nothing to compile, version, or publish differently. The existing cargo invocations and the whole test suite are untouched.
• A new home for CGP's outward comparisons. An agent asked to compare CGP to dependency injection, type classes, effects, or reflection now has a faithful, cited account to build on instead of reconstructing the comparison from memory each time.
• A shared strategy for all public writing. Landing pages, tutorials, blog posts, and social threads now start from one audience model and one set of positioning decisions, so CGP's public material can speak with a single consistent voice rather than drifting per author.
• A stronger front door. The rewritten README.md is now a usable landing page that positions CGP, shows it in code, and draws its own boundary honestly, replacing a stub that pointed elsewhere.
• A faster route into the reference. The new reference Summary lets a reader find the right construct document by the job it does, without scanning the whole directory layout first.
• New synchronization obligations. Every CGP snippet in a related-work document and every CGP claim in a communication-strategy document is now bound by the base's synchronization rule, so a future change to macro syntax or behavior must update these sections too. The communication-strategy section carries the tightest coupling — a single capability appears as a selling point, as the objection it provokes, and as the pain it removes — so edits there ripple across three documents at once.
• Accurate version and toolchain signals. The README now states the correct Rust floor (1.89+), the correct default branch, and the v0.8.0-versus-v0.7.0 compatibility warning, so a reader arriving from crates.io is not misled about what this branch is.