Pony Examples README Conventions
These conventions are derived from existing ponylang examples/README.md files (postgres, redis, lori, crdt, uri, web_link). Follow them when writing or updating an examples/README.md.
Load pony-prose for how the prose reads. This skill says what an examples README holds; pony-prose says how to write it plainly.
Structure
Title — Always # Examples.
Intro paragraph (no heading) — 1-3 sentences describing what the examples are and any useful context. Standard phrasing for library examples: "Each subdirectory is a self-contained Pony program demonstrating a different part of the X library." If examples are ordered by complexity or grouped by category, state that here.
Example entries — One ## heading per example, using the directory name as the heading text. Optionally link to the directory: ## [example-name](example-name/).
Category grouping (when applicable) — If examples fall into natural categories, use ## for category headings and ### for individual examples within each category.
Start-here marker — When one example is clearly the simplest entry point, end its description with: "Start here if you're new to the library."
Example Descriptions
Each example gets a paragraph of 2-4 sentences covering:
- What it does: The concrete workflow in present tense, third person ("Connects to Redis, executes SET, prints the response, and closes the session.")
- What it demonstrates: The specific APIs, interfaces, or patterns exercised, named with backtick formatting (e.g., "
Session.prepare() and NamedPreparedQuery")
- Key concepts: Any non-obvious behavior, design pattern, or protocol detail the example illustrates
Ordering
Choose one strategy and make it clear from the intro paragraph or the order itself:
- By complexity (simplest first) — Best when examples build on each other conceptually. State the ordering in the intro: "Ordered from simplest to most involved."
- By category — Best when examples cover distinct feature areas. Use
## categories with ### examples.
- By directory name — Acceptable when no natural ordering exists.
What to Omit
- Build instructions — Build commands belong in the project's top-level README or Makefile. Exception: if examples have a separate build target (e.g.,
make build-examples), a one-line note in the intro is acceptable.
- Source code snippets — The README describes what each example does; the code speaks for itself.
- Detailed setup instructions — If an example needs external services (a database, Redis server, TLS certificates), mention it briefly in that example's description. Detailed setup belongs in the example's own directory.
1---2name: pony-examples-readme3description: Conventions for Pony examples/README.md files. Load when adding, updating, or reorganizing examples in a ponylang project.4---56# Pony Examples README Conventions78These conventions are derived from existing ponylang examples/README.md files (postgres, redis, lori, crdt, uri, web_link). Follow them when writing or updating an examples/README.md.910Load `pony-prose` for how the prose reads. This skill says what an examples README holds; `pony-prose` says how to write it plainly.1112## Structure13141. **Title** — Always `# Examples`.15162. **Intro paragraph** (no heading) — 1-3 sentences describing what the examples are and any useful context. Standard phrasing for library examples: "Each subdirectory is a self-contained Pony program demonstrating a different part of the X library." If examples are ordered by complexity or grouped by category, state that here.17183. **Example entries** — One `##` heading per example, using the directory name as the heading text. Optionally link to the directory: `## [example-name](example-name/)`.19204. **Category grouping** (when applicable) — If examples fall into natural categories, use `##` for category headings and `###` for individual examples within each category.21225. **Start-here marker** — When one example is clearly the simplest entry point, end its description with: "Start here if you're new to the library."2324## Example Descriptions2526Each example gets a paragraph of 2-4 sentences covering:2728- **What it does**: The concrete workflow in present tense, third person ("Connects to Redis, executes SET, prints the response, and closes the session.")29- **What it demonstrates**: The specific APIs, interfaces, or patterns exercised, named with backtick formatting (e.g., "`Session.prepare()` and `NamedPreparedQuery`")30- **Key concepts**: Any non-obvious behavior, design pattern, or protocol detail the example illustrates3132## Ordering3334Choose one strategy and make it clear from the intro paragraph or the order itself:3536- **By complexity** (simplest first) — Best when examples build on each other conceptually. State the ordering in the intro: "Ordered from simplest to most involved."37- **By category** — Best when examples cover distinct feature areas. Use `##` categories with `###` examples.38- **By directory name** — Acceptable when no natural ordering exists.3940## What to Omit4142- **Build instructions** — Build commands belong in the project's top-level README or Makefile. Exception: if examples have a separate build target (e.g., `make build-examples`), a one-line note in the intro is acceptable.43- **Source code snippets** — The README describes what each example does; the code speaks for itself.44- **Detailed setup instructions** — If an example needs external services (a database, Redis server, TLS certificates), mention it briefly in that example's description. Detailed setup belongs in the example's own directory.
ponylang