Feature Writing
Review and write feature announcements using the 4-part framework: Context, Solution, Usage, Resources.
Workflow
Determine whether the task is a review of existing text or creation of new text, then follow the appropriate workflow.
Review workflow
- Read the target file(s)
- Load
references/feature-writing-guide.md - Check the text against the 4-part framework:
- Does it establish context and articulate the problem?
- Does it describe the solution clearly?
- Does it explain how to use the feature?
- Does it link to supporting resources?
- Check the text against the writing rules:
- Leads with pain, not features
- Uses specific and concrete language
- Avoids unexplained acronyms
- Uses active voice
- Focuses on benefits, not capabilities
- Uses scannable formatting
- Matches tone to the target audience
- Report each finding in this format:
file:line — "original text" — [Rule N.N name] — Suggested: "improved text" - Summarize findings grouped by framework gaps and rule violations
Creation workflow
- Identify the output type (blog post, release note, changelog, customer email, internal communication)
- Load
references/feature-writing-guide.md - Collect the following from the user (ask if missing):
- What problem does this feature solve?
- What was shipped?
- How does a user start using it?
- What resources should be linked?
- Draft using the 4-part framework:
- Context: State the problem and why it matters
- Solution: Describe what was built to solve it
- Usage: Explain how to get started
- Resources: Link to docs, related posts, and references
- Adapt tone and structure to the output type (see Section 3 of the full guide)
- Self-check the draft against all writing rules
- Present the draft with a brief rationale citing the rules applied
Quick reference
Key rules to check first:
| Rule | Summary |
|---|---|
| Lead with pain | Open with the problem, not the feature name |
| Be specific | Use concrete numbers, steps, and scenarios |
| No unexplained acronyms | Spell out on first use or avoid entirely |
| Active voice | "You can now deploy" not "Deployment can be done" |
| Benefits over capabilities | "Save 2 hours per release" not "Supports automation" |
| Scannable structure | Use headings, bullets, and short paragraphs |
| Match tone to audience | Technical for devs, outcome-focused for executives |
| 4-part completeness | Every piece must cover Context, Solution, Usage, Resources |
| Link to resources | Always point readers to docs and related materials |
Full guide
For the complete framework details, writing rules with Do/Don't examples, and output type templates, load references/feature-writing-guide.md.