Enhance Docs

Overview

Improve documentation so it is up to date, coherent, and centered on users' jobs-to-be-done. Favor less content with higher clarity.

Inputs (ask if missing, max 5)

• Docs scope (which files or sections)

• Primary audiences and their jobs-to-be-done

• Source of truth for product behavior (code, APIs, changelog)

• Recent changes or upcoming releases

• Constraints (tone, length, compliance, deadlines)

Principles

• Less is more: reduce noise, keep only what helps users act.

• Low cognitive load: short paragraphs, clear headings, predictable structure.

• High signal: prioritize steps, outcomes, and decision points.

• JTBD-first: structure around what users are trying to accomplish.

Workflow

• Map jobs-to-be-done

• List top 3-5 user jobs and the docs that should enable each.

• Check freshness and accuracy

• Compare docs against current behavior, APIs, and recent changes.

• Simplify and restructure

• Remove redundancy, collapse long lists, and apply progressive disclosure.

• Improve coherence

• Align terminology, fix contradictions, and add consistent cross-links.

• Clarify with examples

• Add minimal examples only where they unblock action.

• Deliver ranked improvements

• Prioritize changes by impact on user success and confusion reduction.

Output Format

Documentation Enhancement

Context Summary

[1-3 sentences]

JTBD Map

• Job: ... -> Docs: ... -> Success criteria: ...

Issues (ranked)

1. [Issue] — impact: high, evidence: ...

Proposed Changes (ranked)

1. [Change] — rationale: ...

Quick Wins

• ...

Open Questions

• ...

Quick Reference

• Trim before adding.

• Structure by jobs and outcomes, not features.

• Keep headings short and action-oriented.

Common Mistakes

• Adding more text instead of removing noise

• Mixing audiences in the same section

• Describing features without user tasks

• Missing cross-links or inconsistent terminology