Structuring a Document: Organising Anything Longer Than a Paragraph | Writing as the Primary Interface Tutorial

Why Structure Matters Independently of Content

Two documents can contain the same facts, arguments, and conclusions and still land very differently, because one is structured for its reader and the other isn't.

Structure determines:

Whether the document gets read at all. An unstructured wall of text doesn't get a careful read; skimmers bounce
What the reader takes away. Structure emphasises certain content and de-emphasises others
How easy it is to revisit. A reader returning a week later should find what they need quickly
Whether the reader can skim usefully. Most readers skim; good structure rewards skimming

Structure is the meta-layer of writing. It doesn't produce the content, but it determines how the content lands.

The Reader Model

Before structuring, picture the reader. Not "a reader" abstractly; a specific imagined one:

What do they know about the topic before starting?
How much time will they give this?
Will they read in one pass, or come back?
On what device? (Mobile reads differently from desktop)
What do they want from this piece of writing?

A reader who'll give your document 90 seconds of skimming needs a different structure than one who'll read it carefully for 30 minutes. Most work documents are read by both kinds of reader, in different proportions at different times.

The Three Reading Modes

Most readers move through long documents in one of three modes:

Skim       run eyes over it, looking for shape and key points (1 minute)
Scan       look for a specific thing (30 seconds to 2 minutes)
Read       engage section by section (5+ minutes)

A well-structured document works for all three:

For skimming: clear headings, a summary, visible structure
For scanning: good section titles, findable keywords, maybe a TOC
For reading: coherent flow, good transitions, dense-but-clear prose

Documents that only work for reading (no skim-friendly structure) get abandoned by most readers. Documents that only work for skimming (no depth) feel thin.

The Inverted Pyramid

For most work documents, start with the most important thing. Put it first. Then supporting material. Then details. Then edge cases.

1. Main point / conclusion / recommendation
2. Key supporting information
3. Context and background
4. Details for interested readers
5. Edge cases, footnotes, appendices

This is the "inverted pyramid" structure from journalism, adapted. A reader can stop at any point and still have the gist.

This is the opposite of what school taught. School essays build up to a conclusion; work documents lead with it. The shift is hard to make but worth it.

TL;DR

Almost every work document longer than a page benefits from a two-to-three-sentence summary at the top. Often labeled "TL;DR" (too long; didn't read) or "Summary" or "Overview".

A good TL;DR:

States the main point clearly
Includes the ask or recommendation (if there is one)
Stands alone: if the reader only reads this, they get the gist

Writing a TL;DR is hard because it forces you to clarify what the document is actually about. If you can't write the TL;DR, the document's thesis is probably unclear.

Section Hierarchy

For documents longer than a page, sections with headings are usually worth it.

Three levels of heading is usually enough:

# Top-level section       major divisions of the document
## Subsection              finer divisions within a section
### Minor subsection       occasional deeper structure; rarely needed

More than three levels is a sign the document is too complex or too nested. Split it, or find a flatter structure.

Writing good headings

Bad headings are vague or generic:

Overview
Background
Details
Conclusion
Next Steps

These give the reader no information. Any document could have these headings.

Good headings describe the content of their section:

Why the current checkout flow loses users
The proposed single-page redesign
Tradeoffs: slower load vs fewer dropoffs
Rollout plan: opt-in A/B through Q3

A reader can skim these headings and understand the document's argument without reading the body. That's what headings are for.

Parallel heading structure

Headings at the same level should be grammatically parallel. Compare:

Bad:    
1. The problem
2. Proposing a solution  
3. Tradeoffs
4. How we'll roll it out

Good:
1. The problem
2. The proposed solution
3. The tradeoffs
4. The rollout plan

Parallelism makes the structure scannable. The reader's eye picks up the pattern and moves through the doc faster.

Lists vs Paragraphs

A common structural decision: list or paragraph?

Use lists when

Items are discrete and parallel (steps, options, criteria)
Order doesn't carry argument (the items aren't building on each other)
Each item is short (a line or two)
Scanning is important (a checklist, a menu)

Use paragraphs when

You're making an argument (which builds)
The content has narrative flow
Items relate with subtle connections
Length varies meaningfully between items

Mistakes

Two common mistakes:

Everything as a list: loses the ability to make nuanced arguments; produces documents that feel like bullet-point collections without connective tissue
Everything as a paragraph: hides what should be easily scannable; makes options or steps hard to extract

Mix both, deliberately. Paragraphs for arguments, lists for items, each for what it's good for.

Emphasis and Visual Weight

Emphasis (bold, italics, occasional inline code) directs the reader's eye. Use sparingly.

When to use bold

The key phrase in a long paragraph
The action in an otherwise descriptive list
The name of a concept on its first introduction
A warning or critical note

When to avoid

As decoration
On whole sentences (at that point, pull the sentence out as its own line)
In every paragraph (dilutes the signal)

Italics

Italics signal emphasis (different from bold's "pay attention"), titles of works, or technical terms. Use less than bold.

Inline code

For anything that's literal text in a technical system: variable names, commands, file paths, config keys. Makes them visually distinct so the reader doesn't read them as prose.

Tables

For data with multiple attributes to compare, tables beat lists and paragraphs.

Option         Cost       Time       Complexity
Rewrite        High       3 months   High
Refactor       Medium     6 weeks    Medium
Patch          Low        1 week     Low

Tables are underused. Many comparisons currently written as paragraphs would be clearer as two-column tables.

Keep tables to a reasonable size. More than 7 columns or 20 rows usually becomes unreadable; split or restructure.

Linking

In most modern documents, links are structural. They let you:

Send context-seeking readers elsewhere without polluting the main doc
Reference other documents as canonical sources
Cite specific lines or sections of other documents
Build a web of interconnected writing

Link generously but purposefully. Every link is a small mental interruption; too many dilute focus.

Good link text is specific:

Bad:    Click here for more.
Better: See the migration plan for details.
Best:   See the Postgres 16 migration plan for details.

The reader should know from the link text whether they want to click.

Length

How long should a document be?

The answer: as long as it needs to be to accomplish its job, and no longer.

Some heuristics:

A Slack message: 1-5 sentences
An email: 100-300 words for most purposes
A ticket: half a page
A PR description: half a page to two pages
A design doc: 2-6 pages
A memo: 1-6 pages (the Amazon six-pager is an upper bound for most contexts)
A longer report / spec: 10-30 pages, usually with a much shorter exec summary

Going significantly over these without a reason is usually padding. Going significantly under is sometimes fine but often leaves the reader guessing.

The Outline

A structural technique: before writing a long document, write its outline first.

Top-level sections
Subsections under each
One sentence per subsection describing its content

The outline is cheap to modify. Rearrange sections at the outline stage, not after writing 4000 words. If the outline doesn't work, neither will the document.

Some writers skip outlining. For short documents that's fine. For anything longer than a few pages, outlines reliably pay back their time.

Structure and AI

A closing note: LLMs produce text that is often sentence-clear but structure-weak. Default LLM output drones. No clear section boundaries, no strong TL;DR, weak heading discipline, too-evenly-sized paragraphs.

If you use AI for drafts, structure is usually where you add the most value. Take the AI's sentences, strip them, restructure for your specific reader, add the TL;DR the AI missed, rewrite the headings so they describe content, and cut the evenly-sized paragraphs into a mix that reflects real emphasis.

The sentences can come from the machine. The structure has to come from you.

Common Pitfalls

"I'll structure it after I write it." Often works for short documents. For long ones, pre-structuring (outlining) saves significant rewriting

"Headings feel too formal." For Slack messages, fair. For anything over half a page, headings reduce the reader's effort. Not formal; just legible

"I want the reader to read it all." You do, and they won't. Design for skimming; the readers who read everything also benefit from the structure

"Lists are for lazy writers." Lists are for discrete items. Not every list is lazy; lazy writers overuse both lists and paragraphs

"Short is always better." Not always. Complex ideas sometimes need room. The test is whether each sentence earns its place, not whether the document is short in absolute terms

Next Steps

Continue to 08-editing.md for how to turn a first draft into a finished document.