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.