Inverted Pyramid Documentation Model
Editorial guidelines and structural standards for authoring technical articles, README files, API references, and developer documentation using the Inverted Pyramid model—ensuring readers extract immediate, actionable value above the fold while details cascade progressively downward.
1. Core Philosophy: Information Cascading
The Inverted Pyramid model organizes content by reader utility rather than author chronology:
graph TD
A["[High Value] Summary & Prescribed Core Actions"] --> B["[Medium Value] Usage, Workflows & Setup"]
B --> C["[Detail Value] Development, Testing & Architecture"]
C --> D["[Low Value] Internal Implementation & Compliance"]
The 3 Reader Archetypes
Every technical document must cater to three distinct reading depths:
- The Scanner (5–10 seconds): Reads the headline, grabs the installation/execution command, and starts working immediately.
- The Operator (2–5 minutes): Reads usage tables, CLI flags, workflow checklists, and common recipes.
- The Contributor / Architect (10+ minutes): Explores internal architecture, build pipelines, design decisions, and compliance boundaries.
2. Standard Document Structures
A. README & Project Documentation Hierarchy
User-facing project documentation must follow this strict structural sequence:
- Title & High-Impact Summary:
- Short, active one-sentence hook explaining what the project is, what problem it solves, and why it exists.
- Prescribed Actions (Immediate Quickstart):
- Copy-paste installation command (
npx ..., go install ..., pip install ..., cargo install ...).
- Single highest-value initial command to verify setup or produce output.
- Usage Guides & Workflows:
- Common CLI flags, arguments, configuration options, and copy-pasteable recipes.
- Output examples and expected terminal responses.
- Developer & Contributor Instructions:
- How to clone, build locally, execute test suites, run linters, and verify builds.
- Technical Architecture & Internals:
- Subsystem designs, data schemas, module boundaries, and trade-off rationales.
- Legal & Compliance:
- License identifier, copyright, contributing links, and security policies.
B. Technical Article & Blog Post Hierarchy
- Above the Fold (Lead Block - First 150 words):
- State the core thesis, metric improvement, or direct answer immediately.
- Do not open with generic throat-clearing ("In today's fast-paced world of technology...").
- The Visual / Working Example:
- Provide a working code snippet or architectural diagram within the first two scrolls.
- Step-by-Step Breakdown & Nuance:
- Implementation steps, edge cases, configuration details, and benchmarking data.
- Actionable Takeaways & Next Steps:
- Concrete next actions, repository links, and references.
3. Structural Rules & Editorial Principles
- Lead with Action: Never bury installation commands behind paragraphs of architectural theory. Let the user run the tool first.
- Sentence-Case Headings: Keep headings clear, concise, and sentence-cased, leading with high-value nouns or active verbs.
- Table Density: Use tables for CLI flags, tool comparisons, and option summaries rather than loose bullet lists.
- Copy-Paste Code Blocks: Every command block must be complete and ready to execute without editing placeholders unless explicitly highlighted.
1---2name: inverted-pyramid3description: Structural guide and editorial model for organizing technical articles, developer documentation, and READMEs. Applies the Inverted Pyramid model to place high-value summaries and actionable quickstarts first, cascading down to usage workflows, architectural details, and compliance. Activate when structuring technical articles, writing or refactoring README files, organizing documentation hierarchy, or making technical guides scannable.4license: Apache-2.05---67# Inverted Pyramid Documentation Model89Editorial guidelines and structural standards for authoring technical articles, README files, API references, and developer documentation using the **Inverted Pyramid** model—ensuring readers extract immediate, actionable value above the fold while details cascade progressively downward.1011---1213## 1. Core Philosophy: Information Cascading1415The **Inverted Pyramid** model organizes content by reader utility rather than author chronology:1617```mermaid18graph TD19 A["[High Value] Summary & Prescribed Core Actions"] --> B["[Medium Value] Usage, Workflows & Setup"]20 B --> C["[Detail Value] Development, Testing & Architecture"]21 C --> D["[Low Value] Internal Implementation & Compliance"]22```2324### The 3 Reader Archetypes25Every technical document must cater to three distinct reading depths:261. **The Scanner (5–10 seconds)**: Reads the headline, grabs the installation/execution command, and starts working immediately.272. **The Operator (2–5 minutes)**: Reads usage tables, CLI flags, workflow checklists, and common recipes.283. **The Contributor / Architect (10+ minutes)**: Explores internal architecture, build pipelines, design decisions, and compliance boundaries.2930---3132## 2. Standard Document Structures3334### A. README & Project Documentation Hierarchy3536User-facing project documentation **must** follow this strict structural sequence:37381. **Title & High-Impact Summary**:39 - Short, active one-sentence hook explaining what the project is, what problem it solves, and why it exists.402. **Prescribed Actions (Immediate Quickstart)**:41 - Copy-paste installation command (`npx ...`, `go install ...`, `pip install ...`, `cargo install ...`).42 - Single highest-value initial command to verify setup or produce output.433. **Usage Guides & Workflows**:44 - Common CLI flags, arguments, configuration options, and copy-pasteable recipes.45 - Output examples and expected terminal responses.464. **Developer & Contributor Instructions**:47 - How to clone, build locally, execute test suites, run linters, and verify builds.485. **Technical Architecture & Internals**:49 - Subsystem designs, data schemas, module boundaries, and trade-off rationales.506. **Legal & Compliance**:51 - License identifier, copyright, contributing links, and security policies.5253---5455### B. Technical Article & Blog Post Hierarchy56571. **Above the Fold (Lead Block - First 150 words)**:58 - State the core thesis, metric improvement, or direct answer immediately.59 - Do not open with generic throat-clearing (*"In today's fast-paced world of technology..."*).602. **The Visual / Working Example**:61 - Provide a working code snippet or architectural diagram within the first two scrolls.623. **Step-by-Step Breakdown & Nuance**:63 - Implementation steps, edge cases, configuration details, and benchmarking data.644. **Actionable Takeaways & Next Steps**:65 - Concrete next actions, repository links, and references.6667---6869## 3. Structural Rules & Editorial Principles7071- **Lead with Action**: Never bury installation commands behind paragraphs of architectural theory. Let the user run the tool first.72- **Sentence-Case Headings**: Keep headings clear, concise, and sentence-cased, leading with high-value nouns or active verbs.73- **Table Density**: Use tables for CLI flags, tool comparisons, and option summaries rather than loose bullet lists.74- **Copy-Paste Code Blocks**: Every command block must be complete and ready to execute without editing placeholders unless explicitly highlighted.
danicat