75 lines
2.1 KiB
Markdown
75 lines
2.1 KiB
Markdown
# DOCS — Public `README.md` scaffold
|
|
|
|
`README.md` is the first file a new reader (human OR agent) opens. One file, nine sections, in this order. Keep ≤ 300 lines; longer material lives in `docs/`.
|
|
|
|
**Nine-section template:**
|
|
|
|
```markdown
|
|
# {{PROJECT_NAME}}
|
|
|
|
> One-line pitch (what + why, ≤ 100 chars).
|
|
|
|
[](link) [](link) [](link)
|
|
|
|
## What
|
|
2-3 sentences: what it does, who it's for. No marketing adjectives.
|
|
|
|
## Why
|
|
2-3 sentences: problem this solves, alternatives considered, why this one.
|
|
Link to the relevant ADR: [DECISIONS.md](DECISIONS.md#adr-nnnn).
|
|
|
|
## Install
|
|
```bash
|
|
# Primary path — the 90% case
|
|
<one command>
|
|
```
|
|
|
|
**Prerequisites:** <language X >= vN, OS constraints, system deps>.
|
|
|
|
<If needed: alternative install methods in `docs/install.md`.>
|
|
|
|
## Usage
|
|
Smallest working example. Copy-pasteable.
|
|
```bash
|
|
<command producing visible output>
|
|
```
|
|
|
|
Link to a richer quickstart in `docs/quickstart.md` if >20 lines.
|
|
|
|
## Development
|
|
```bash
|
|
git clone <repo>
|
|
cd <repo>
|
|
<bootstrap command, e.g. cargo build>
|
|
<test command>
|
|
```
|
|
|
|
Project layout:
|
|
- `src/` — implementation
|
|
- `tests/` — integration tests
|
|
- `docs/` — long-form docs
|
|
- `{{STACK}}-specific notes → link>
|
|
|
|
## Deploy
|
|
Target: **{{DEPLOY}}**. One-liner: `<deploy command>`.
|
|
Full runbook: `docs/runbooks/deploy.md`.
|
|
|
|
## Architecture
|
|
One paragraph + one Mermaid diagram (see `_blocks/docs-architecture-diagrams.md`). Detail in `docs/architecture.md`.
|
|
|
|
## Contributing
|
|
- Issue tracker: <url>
|
|
- Commit convention: Conventional Commits (see `_blocks/git-conventions` in kit)
|
|
- PR checklist: `docs/CONTRIBUTING.md`
|
|
|
|
## License
|
|
<SPDX id> — see [LICENSE](LICENSE).
|
|
```
|
|
|
|
**Rules:**
|
|
- No secrets (RULE 0.8). No literal tokens.
|
|
- Install command must be ONE command for the happy path.
|
|
- Every "see docs/X" link must resolve — scaffolder verifies or creates the target.
|
|
- If the project is private / not publicly deployable (banned list per `rules/security.md`), mark the repo header with `<!-- PRIVATE — do not publish -->` and omit public badges.
|
|
|
|
**Source:** standard-readme spec (RichardLitt/standard-readme) [E4]; GitHub "About READMEs" [E4].
|