crafting-effective-readmeslisted

# Crafting Effective READMEs ## Overview READMEs answer questions your audience will have. Different audiences need different information - a contributor to an OSS project needs different context than future-you opening a config folder. **Always ask:** Who will read this, and what do they need to know? ## Process ### Step 1: Identify the Task **Ask:** "What README task are you working on?" | Task | When | |------|------| | **Creating** | New project, no README yet | | **Adding** | Need to document something new | | **Updating** | Capabilities changed, content is stale | | **Reviewing** | Checking if README is still accurate | ### Step 2: Task-Specific Questions **Creating initial README:** 1. What type of project? (see Project Types below) 2. What problem does this solve in one sentence? 3. What's the quickest path to "it works"? 4. Anything notable to highlight? > **Before finalizing:** Do not assert commands without a run check. Actually run every install/usage command you drafted and confirm it works — do not rely on recall of how the tooling behaves. Mark any command you cannot run as `[unverified]`. (The Reviewing path already checks content against project state; the Creating path must verify the commands it introduces.) **Adding a section:** 1. What needs documenting? 2. Where should it go in the existing structure? 3. Who needs this info most? **Updating existing content:** 1. What changed? 2. Read current README, identify stale sections 3. Propose specifi