Course contentsShow
← Software Engineering
Lesson 1690 of 1,93349. Technical Writing and DocumentationFree lesson

The Inverted Pyramid Structure

Organizing documentation with the most important information first, allowing readers to get value quickly and dive deeper as needed.

The Inverted Pyramid Structure

You'll learn how to organize technical documentation so readers get the most critical information first, then progressively deeper details.

What Is the Inverted Pyramid?

The inverted pyramid is a writing structure borrowed from journalism where you place the most important information at the top, followed by supporting details, and finally background or contextual information at the bottom. In technical documentation, this means answering the reader's most urgent question immediately, then providing progressively more depth for those who need it.

Think of it like a news article: the headline and first paragraph tell you everything essential. If you only read that, you're informed. Each subsequent paragraph adds detail, but you can stop reading at any point and still have gotten value.

Why This Matters in Documentation

Engineers are busy. When someone opens your API documentation, README, or troubleshooting guide, they usually have a specific, urgent question: "How do I authenticate?" or "Why is this failing?" The inverted pyramid respects their time.

Structure example:

  1. Top (Critical): What it does, the immediate answer
  2. Middle (Important): Common use cases, parameters, examples
  3. Bottom (Context): Edge cases, historical reasons, alternative approaches

For instance, in API reference documentation, start with the function signature and a one-line description. Then show a basic code example. Only afterward explain every parameter in detail or discuss advanced scenarios.

Applying It

In a README: put installation and quick-start first, not a history of why you built it. In a design document: state the decision upfront, then explain rationale. In release notes: list breaking changes before enhancements.

Key Takeaway: Put conclusions first, details second—readers decide their own depth, and everyone gets value faster.