| name | inverted-pyramid |
| description | Structuring style to prioritize highest value information (actions, summaries) at the beginning, followed by usage, developer instructions, and finishing with implementation details and legal/compliance. Use when this capability is needed. |
| metadata | {"author":"danicat"} |
Inverted pyramid documentation model
This skill provides editorial guidelines for structuring technical articles, README files, and documentation using the inverted pyramid model. It ensures you place high-value information at the beginning. This allows readers to extract value immediately, with details cascading downward.
1. Trigger conditions
Activate this skill when you:
- Structure, refactor, or write project
README.md files.
- Draft technical user guides, API manuals, or tool instructions.
- Audit existing documentation for scannability and reading efficiency.
2. Core philosophy: Information cascading
The inverted pyramid structure places the most critical, high-impact, or actionable information at the top. Secondary user details, operational steps, and low-impact implementation details follow:
graph TD
A["[High Value] Summary & core actions"] --> B["[Medium Value] Usage & setup"]
B --> C["[Detail Value] Development & testing"]
C --> D["[Low Value] Implementation & legal"]
3. README structural sequence
For README.md and user-facing project guides, documents must follow this exact sequence:
- Title and high-impact summary: A short, active hook explaining the project, the problem it solves, and its core capabilities.
- Prescribed actions: Immediate, copy-paste installation or execution commands. This is the highest-value action a user can take.
- User documentation and usage guides: Clear details on tools, prompts, command-line flags, and standard user workflows.
- Developer instructions: How to compile locally, execute test suites, run linters, and trigger release hooks.
- Development documentation: In-depth technical architecture, package structures, and internal mechanics.
- Legal and compliance: Copyright notices, license specifications, and support boundaries. This is the least active piece of information.
4. Writing principles
- Lead with action: don't hide installation instructions behind paragraphs of architectural theory. Let the user run the tool first.
- Vary reading depth: Ensure the document caters to three reading styles:
- The scanner: Reads the title and copies the quick-start command in seconds.
- The operator: Reads the usage tables and workflow guides in minutes.
- The contributor: Reads the build and architecture details in depth.
- Sentence case headings: Always keep headings in sentence case, prioritizing high-value nouns first.
Source: danicat/speedgrapher — distributed by TomeVault.
