Skip to content

docs(claude): size help-text prose to the behavior's share of the command #3772

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
max-sixty merged 1 commit into from
Aug 8, 2026
Merged

docs(claude): size help-text prose to the behavior's share of the command #3772

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -163,6 +163,8 @@ Each command has three documentation pieces in `src/cli/mod.rs`:

4. **after_long_help should mostly stand alone** — The opener should give context or purpose, not just continue with details that only make sense after reading the definition. Avoid non-sequiturs.

5. **Give a behavior the share of the docs that matches its share of the feature** — every paragraph is read by everyone who runs `--help`, so length is a claim on that attention. A guard or edge case that is a tiny share of the command usually gets zero words: its own error message states it at the moment it matters, and the help page leaves it implicit. Reserve prose for what most users of the command meet.

**Good patterns for after_long_help openers:**

- Explain the mental model: "Worktrees are addressed by branch name..."
Expand Down
Loading