Kind: leaf
Effort: S · Risk: low
Source: jessfraz/dotfiles (run 2026-08-23)
Decision: adopt
Problem
Finding out what this repo can do means reading the Makefile.
Current state (this repo)
The Makefile has 20 targets and the default target prints "Cowardly refusing to run on . Use platform specific targets." -- it declines to act without saying which targets exist. Several are non-obvious from their names (skip-mutable-settings, unskip-mutable-settings, restore-preferences, init-submodules), and their explanations live in comments above the rule, visible only when reading the file.
Their approach
Every target carries a ## description on the rule line, and make help greps the makefile and prints an aligned, colorized target/description table. The documentation cannot drift out of the file it documents because it is on the same line as the rule.
Difference that matters
Where target documentation lives. Ours is in comments above rules — good for a reader of the file, invisible to someone at a prompt. Theirs is one line and one grep, and it stays correct because renaming a target moves its description with it.
Translation into this repo
Append ## <description> to each target line and add the standard help grep/awk rule. Make help the default target instead of the current refusal message, which then still refuses to build anything but at least tells you what is available. The long explanatory comments stay where they are — the ## text is a one-line summary, not a replacement for them.
Kind: leaf
Effort: S · Risk: low
Source: jessfraz/dotfiles (run 2026-08-23)
Decision: adopt
Problem
Finding out what this repo can do means reading the Makefile.
Current state (this repo)
The Makefile has 20 targets and the
defaulttarget prints "Cowardly refusing to run on . Use platform specific targets." -- it declines to act without saying which targets exist. Several are non-obvious from their names (skip-mutable-settings,unskip-mutable-settings,restore-preferences,init-submodules), and their explanations live in comments above the rule, visible only when reading the file.Their approach
Every target carries a
## descriptionon the rule line, andmake helpgreps the makefile and prints an aligned, colorized target/description table. The documentation cannot drift out of the file it documents because it is on the same line as the rule.Difference that matters
Where target documentation lives. Ours is in comments above rules — good for a reader of the file, invisible to someone at a prompt. Theirs is one line and one grep, and it stays correct because renaming a target moves its description with it.
Translation into this repo
Append
## <description>to each target line and add the standardhelpgrep/awk rule. Makehelpthedefaulttarget instead of the current refusal message, which then still refuses to build anything but at least tells you what is available. The long explanatory comments stay where they are — the##text is a one-line summary, not a replacement for them.