README Authoring (Deep Workflow)
A README is the front door of a repository. Optimize for time-to-first-success: install, run, verify—then add depth for contributors and operators.
When to Offer This Workflow
Trigger conditions:
- New repo; users cannot get running from docs alone
- Open-source release needing clear license and support expectations
- Internal library consumed by many teams
Initial offer:
Use six stages: (1) audience & promise, (2) above-the-fold, (3) quickstart, (4) configuration & operations, (5) contributing & governance, (6) maintenance). Confirm package ecosystem and license.
Stage 1: Audience & Promise
Goal: First paragraph states what the project does, for whom, and non-goals if confusing.
Exit condition: Reader knows in 30 seconds if this repo matches their need.
Stage 2: Above the Fold
Goal: Title, optional badges (CI, version, license), one screenshot or demo GIF if UI helps.
Practices
- Link out to a full docs site when README would exceed ~300 lines
Stage 3: Quickstart
Goal: Copy-paste commands that work on a clean machine; pin versions or point to release tags.
Include
- Prerequisites (runtime, tools)
- Install and the first command with expected output shape
Stage 4: Configuration & Operations
Goal: Environment variables table with defaults; ports; production notes (TLS, scaling, observability).
Security
- Never document real secrets; reference secret stores and rotation
Stage 5: Contributing & Governance
Goal: Link CONTRIBUTING.md, code of conduct, issue/PR templates; security disclosure policy for OSS.
Stage 6: Maintenance
Goal: Changelog link or release notes; owning team; deprecation notices when relevant.
Final Review Checklist
- [ ] Opening clarifies purpose and audience
- [ ] Quickstart verified on a fresh machine or CI
- [ ] Configuration and security expectations documented
- [ ] Contributing and license paths clear
- [ ] Maintenance signals (changelog, ownership) present
Tips for Effective Guidance
- Run quickstart in CI (Docker or script) for critical OSS projects.
- Keep README skimmable; move deep dives to
docs/. - For libraries: link API reference and migration guides prominently.
Handling Deviations
- Monorepo: root README as an index to packages with one-liner descriptions each.