Scrolls
7 min read
On this page

Structure Before Prose

Most people sit down to write and immediately start composing sentences. This is backwards. Structure comes first. An outline is to writing what architecture is to code — get it wrong and no amount of polished implementation will save you.

A well-structured document with mediocre prose is usable. A beautifully written document with bad structure is not. Readers can tolerate clunky sentences if the information is organized logically. They cannot tolerate elegant paragraphs that wander without direction.

Why Outline First

An outline forces you to answer the hard question before you get lost in the details: what is this document actually about, and in what order does the reader need the information?

Writing without an outline is like coding without a plan. You start with whatever is top of mind, add sections as you think of them, and end up with a document that follows the order you thought of things rather than the order the reader needs them. The result is a stream of consciousness wearing a document's clothes.

Writing without an outline:
1. Start writing the introduction
2. Realize you need background context
3. Add a background section after the introduction
4. Jump to implementation details because you're excited about them
5. Remember you haven't stated the problem yet
6. Bolt a problem statement onto the beginning
7. Add a conclusion that summarizes a different document
   than the one you actually wrote

Writing with an outline:
1. List the key points the reader needs
2. Order them logically
3. Check: does each point follow from the previous one?
4. Check: could a reader skim the headings and get the gist?
5. Now write the prose to fill each section

Outlining takes ten minutes. It saves hours of restructuring. More importantly, it produces documents that readers can actually follow.

The Inverted Pyramid

Journalism figured this out a century ago: put the most important information first. The inverted pyramid structure leads with the conclusion, follows with supporting details, and ends with background context.

Traditional structure (chronological):
1. Background and history
2. What we investigated
3. What we found
4. Analysis of findings
5. Conclusion and recommendation

Inverted pyramid:
1. Recommendation / conclusion / answer
2. Key evidence supporting it
3. Detailed analysis
4. Background for those who need it

The inverted pyramid respects a basic reality: most readers do not finish documents. They read until they have what they need, then stop. If your conclusion is on page 5, most readers will never see it.

This applies to every level of a document:

  • The document as a whole: lead with the main point
  • Each section: lead with that section's key message
  • Each paragraph: lead with the topic sentence
Buried conclusion:
"We evaluated three database options over the past two weeks.
We tested PostgreSQL, MySQL, and CockroachDB across seven
benchmarks including read throughput, write throughput, failover
time, and operational complexity. PostgreSQL scored highest on
four benchmarks, MySQL on two, and CockroachDB on one. Considering
our team's existing expertise and the benchmark results, we
recommend PostgreSQL."

Inverted pyramid:
"We recommend PostgreSQL. It outperformed MySQL and CockroachDB
on four of seven benchmarks, and our team already has deep
operational experience with it. The full benchmark comparison
is below."

The second version respects the reader who only has 30 seconds. They get the answer immediately. The reader who wants the full analysis can keep reading.

Headings as a Scannable Story

Your headings should tell a story on their own. A reader who only reads the headings should walk away with a reasonable understanding of the document's content and argument.

Test this by extracting just the headings and reading them in sequence. Do they make sense? Do they progress logically? Could someone reconstruct the document's main argument from the headings alone?

Bad headings (vague, uninformative):
## Background
## Discussion
## Analysis
## Details
## Conclusion

Better headings (specific, tells a story):
## Payment Processing Latency Has Doubled Since January
## Root Cause: Synchronous Fraud Check on Every Transaction
## Proposed Fix: Move Fraud Checks to an Async Pipeline
## Expected Impact: 60% Latency Reduction at 15% Fraud Check Delay
## Migration Plan: Three-Phase Rollout Over 4 Weeks

The bad headings could belong to any document about any topic. The better headings tell you exactly what the document argues, even if you never read a single paragraph.

Heading levels matter too. Use ## for major sections and ### for subsections within them. Do not skip levels. Do not use more than three levels — if you need a ####, your document probably needs restructuring rather than deeper nesting.

Structure for Skimmers

Accept this fact: most of your readers will skim. Studies consistently show that people read about 20-28% of the words on a page. For technical documents, that number is probably lower.

This is not a failure of your readers. It is rational behavior. People are busy. They are looking for the specific information they need, not reading for pleasure. Your job is to make skimming effective.

Techniques that help skimmers:

Front-load every section. The first sentence of every section should deliver that section's main point. A skimmer who reads only first sentences should get 80% of your message.

Hard to skim:
"After considerable discussion among the team, and taking into
account the various factors we've been weighing for the past
several weeks, including cost, performance, and maintainability,
we've arrived at the conclusion that rewriting the service is
the right approach."

Easy to skim:
"We should rewrite the service. The current codebase has
accumulated enough technical debt that incremental fixes cost
more than a clean rewrite. Here's our analysis."

Use lists for parallel items. When you have three or more related points, use a bulleted or numbered list instead of burying them in a paragraph. Lists are visually scannable in a way that paragraphs are not.

Hard to skim:
"The migration affects the user service, the payment service,
and the notification service. The user service needs a schema
change, the payment service needs a new API endpoint, and the
notification service needs updated templates."

Easy to skim:
The migration affects three services:
- User service: schema change required
- Payment service: new API endpoint needed
- Notification service: template updates needed

Use bold text for key terms and phrases. But use it sparingly. If everything is bold, nothing is bold. Reserve emphasis for the words that a skimmer absolutely must catch.

Keep paragraphs short. Three to five sentences is ideal for technical writing. A wall of text signals to a skimmer that this section is not worth the effort. Short paragraphs create visual breaks that make scanning easier.

Use tables for comparisons. When comparing options, features, or trade-offs, a table communicates more efficiently than prose.

Hard to compare in prose:
"PostgreSQL supports JSON queries and has excellent tooling, but
requires manual sharding. MySQL is well-known and easy to operate
but lacks native JSON support. CockroachDB handles sharding
automatically but has a smaller ecosystem."

Easy to compare in a table:
| Criteria      | PostgreSQL | MySQL   | CockroachDB |
|---------------|-----------|---------|-------------|
| JSON support  | Native    | Limited | Native      |
| Auto-sharding | No        | No      | Yes         |
| Ecosystem     | Large     | Large   | Growing     |
| Team expertise| High      | Medium  | Low         |

Common Document Structures

Different document types have established structures. Do not reinvent them. Using a familiar structure helps readers navigate because they know what to expect.

Decision documents (design docs, RFCs):

1. Summary / recommendation
2. Context / problem statement
3. Proposed solution
4. Alternatives considered
5. Risks and mitigations
6. Next steps / timeline

Incident reports / post-mortems:

1. Summary (what happened, impact, duration)
2. Timeline of events
3. Root cause analysis
4. What went well
5. What went poorly
6. Action items

Technical tutorials / how-to guides:

1. What you will accomplish
2. Prerequisites
3. Step-by-step instructions
4. Verification / testing
5. Troubleshooting common issues

Status updates / progress reports:

1. Summary (on track / at risk / blocked)
2. What was accomplished
3. What's next
4. Blockers and risks

Deviating from these structures is fine when you have a reason. But start with the convention and modify it, rather than building from scratch every time.

The Outline Process

Here is a practical method for outlining:

  1. Brain dump. List every point you might want to include. Do not organize yet. Just get everything out of your head and onto the page.

  2. Identify the main message. What is the single most important thing your reader should take away? Write it in one sentence. This is your thesis.

  3. Group related points. Cluster your brain dump into logical groups. Each group becomes a section.

  4. Order the groups. Put them in the sequence the reader needs. Usually this means: conclusion first, then supporting evidence, then background.

  5. Write headings. Turn each group into a specific, informative heading. Read the headings in sequence. Do they tell a coherent story?

  6. Add sub-points. Under each heading, note the key points that section needs to cover. These become your paragraphs.

  7. Check the flow. Does each section lead naturally to the next? Are there gaps where the reader would be confused? Are there sections that belong elsewhere?

Example outline for a migration proposal:

Thesis: We should migrate from Elasticsearch to OpenSearch
to reduce licensing costs by $84K/year with minimal risk.

## We Should Migrate from Elasticsearch to OpenSearch
   - Cost savings: $84K/year in licensing
   - API-compatible: minimal code changes required
   - Risk is low due to compatibility

## Current Elasticsearch Costs Are Unsustainable
   - License cost breakdown
   - Growth projections at current trajectory
   - Comparison to OpenSearch pricing

## Migration Plan: 3 Phases Over 8 Weeks
   - Phase 1: Shadow traffic (weeks 1-2)
   - Phase 2: Gradual cutover (weeks 3-6)
   - Phase 3: Decommission Elasticsearch (weeks 7-8)

## Risks & Mitigations
   - Plugin compatibility: tested, 2 of 14 need updates
   - Performance: benchmarked at equivalent throughput
   - Rollback plan: keep ES cluster warm for 2 weeks

## Alternatives Considered
   - Renegotiate Elasticsearch license (tried, marginal savings)
   - Migrate to Solr (higher migration cost, less compatibility)
   - Build custom search (rejected, too much investment)

This outline took maybe 15 minutes. It will save hours of writing and rewriting, and it produces a document that a reader can navigate efficiently.

Common Pitfalls

Starting with background. The most common structural mistake in technical writing is opening with extensive background and history before getting to the point. Your reader wants the answer first. Put the context after, for those who need it.

Organizing by your thought process instead of the reader's needs. You discovered the root cause of a bug by first checking the logs, then examining the database, then reviewing the code. Your post-mortem should not follow that chronological order. It should lead with the root cause, then provide evidence.

Using headings as labels instead of messages. "Database" is a label. "Migrate to PostgreSQL for 3x Query Performance" is a message. Labels force the reader to read the section to learn what it says. Messages communicate even to skimmers.

Over-nesting. If your outline has sections numbered 3.2.4.1, your structure is too deep. Flatten it. Deep nesting makes documents harder to navigate, not easier.

Treating the outline as permanent. Outlines should evolve as you write. Sometimes you discover that a section does not work, two sections should merge, or a new section is needed. The outline is a starting point, not a contract. Adjust it, but adjust deliberately rather than drifting.

Key Takeaways

  • Outline before you write. Ten minutes of outlining saves hours of restructuring.
  • Use the inverted pyramid: lead with the conclusion, follow with supporting evidence, end with background.
  • Write headings that tell a story. A reader who only reads headings should understand your document's main argument.
  • Structure for skimmers. Front-load sections, use lists and tables, keep paragraphs short, and use bold sparingly for key terms.
  • Use established structures for common document types. Do not reinvent the format for design docs, post-mortems, or status updates.
  • Your document's structure should follow the reader's needs, not the order you thought of things.