Skip to content
Published on

How to Communicate Through Documents — Writing That Gets Read Again

🇰🇷KO🇺🇸EN🇯🇵JA
Split View필사 모드
Authors

Opening: Speech Is Heard Once, a Document a Hundred Times

In my days at LINE, one wiki document a colleague left behind when he resigned stayed with me for a long time. After he was gone, that document survived and was read again whenever a new hire joined. Dozens of people read it over a year. He wrote it just once, but that writing worked dozens of times.

I have the opposite experience too. There was once a feature with no record at all of who built it, why, or how, so I had to trace it through the code alone for a long while. The person who wrote it had already left, and the context he carried in his head left with him. That was when it hit me hard: knowledge not committed to a document dies the moment the person who knows it leaves.

Speech evaporates. No matter how clearly you explain in a meeting, it never reaches those who weren't there, and even those who were forget half of it within a week. Documents are different. A document doesn't sleep, it crosses time zones, and it remains after the person is gone.

This is not about fancy writing technique. It is about how to write practical documents that "get read again" — that do their job even as time passes, even when the author is not around.

The Core Insight: Documents Are the Center of Collaboration and Handoff

Building software is, at its core, collaboration. And more than half of collaboration is "moving knowledge" — moving what's in my head into someone else's. The medium of that movement is the document.

Documents matter because of three asymmetries.

First, the asymmetry of time. A piece of writing is written once but read many times, at many moments. If I spend 30 extra minutes writing so that 50 readers each save 5 minutes, that is an overwhelmingly profitable investment.

Second, the asymmetry of space. Distributed teams, different time zones, different offices. You can't gather everyone in one room. A document is the only scalable means to let everyone access the same information.

Third, the asymmetry of people. People leave. They change jobs, move departments, take vacation. Knowledge stored only in a person disappears with that person. A document keeps the departed person's knowledge in the organization.

Code tells you "how." Documents tell you "why." And the question that torments you most six months later is always "why."

So a good document is a kind handoff. It is a letter to a future colleague, and to your own self six months from now who has forgotten everything.

Because It's Read Again and Again, Write It With Care

A crucial shift in perspective is needed here. A document is not "something you write" but "something that gets read." The value of writing arises not at the moment of writing but at the moment of reading.

From this viewpoint, the cost structure of writing flips. The time I spend writing is one-time. But the time people spend reading it is multiplied by the number of reads. For a document a hundred people will read, polishing a sentence for one extra minute to cut each reader's comprehension time by even 10 seconds saves an enormous amount of time overall.

So the more often a document is read, the more carefully it should be written. A throwaway note read once and an onboarding guide referenced by dozens for a long time deserve different levels of effort.

There is a decisive information asymmetry between author and reader. The author holds all the context in their head, while the reader starts from a blank slate. That one line the author omitted because it seemed too obvious becomes, for the reader, a decisive hole that prevents understanding the whole document. This is what cognitive psychology calls the "curse of knowledge" — the trap of unconsciously assuming others know what you know.

A careful document consciously breaks this curse. It constantly asks, "Could someone seeing this for the first time understand it?" That is the starting point of writing that gets read again.

The Structure of a Good Document: Purpose, Context, Conclusion First

The most common and fatal mistake is writing "in chronological order" — in the order you learned things, that is, starting from background, going through the process, and arriving at the conclusion. This is natural for the author but torture for the reader. The reader wants to know the conclusion quickly, but it appears only after reading to the end.

A good document puts the conclusion first. It is like the "inverted pyramid" structure of a newspaper article, which places the core in the first paragraph. Amazon's internal six-page document culture and the military principle "BLUF (Bottom Line Up Front)" share the same philosophy.

A recommended document skeleton looks like this.

[Title] — what the document is about, at a glance

1. One-line summary (TL;DR)
   - The single thing you need to know from this document

2. Purpose / Background
   - Why this document exists
   - Who should read it

3. Conclusion / Core claim
   - What to do, what was decided

4. Rationale / Detail
   - Why we reached that conclusion
   - Alternatives considered and trade-offs

5. Execution / Next steps
   - Concretely who does what by when

6. References / Appendix
   - Related links, terms, additional materials

The key to this structure is the "inverted pyramid." The most important information is at the top, and detail increases as you go down. So a busy reader can read just the top three items and leave, while a reader who needs depth can read to the end. The same document satisfies readers of different depths.

One more principle: always leave the "why." "What was done" survives in the code and the artifact, but "why it was done that way" lives only in the author's head. When someone asks six months later, "Why was this done this way?", if the answer is in the document, that document is gold. Especially, writing down alternatives considered but not adopted, and the reasons, prevents someone in the future from repeating the same deliberation.

Consideration for the Reader: Whom Are You Writing For?

A good document is written with the reader in mind. You must first decide, "Who is the first reader of this writing?"

The same content must be written differently depending on the reader.

Reader typeWhat they wantWhat the document should emphasize
Decision-makerConclusion and impactSummary, cost, risk, recommendation
Fellow developerHow to implement and whyDesign rationale, trade-offs, example code
New hireThe whole contextBackground, term definitions, step-by-step guide
Future meThe basis of the decisionWhy it was decided, record of alternatives

Concrete practices of consideration for the reader are as follows.

First, expand jargon when you first use it. Spell out abbreviations once and put the abbreviation in parentheses. Internal terms familiar to the author can be alien language to the reader.

Second, make it scannable. People skim documents rather than read them closely. Use headings, bold, bullet points, and tables so the structure is visible at a glance. If a paragraph exceeds five lines, consider breaking it up.

Third, give examples. One concrete example beats ten lines of abstract explanation. Showing "do it this way" and "don't do it this way" side by side speeds up understanding dramatically.

Fourth, make the reader's next action clear. So that a reader who finishes the document doesn't ask, "So what do I do now?", write the next step plainly.

Asynchronous Communication: When a Document Replaces a Meeting

The document is the core tool of asynchronous communication — communication that doesn't require everyone to be in the same place at the same time.

Meetings (synchronous communication) are powerful but expensive. They tie up everyone's time at the same moment, evaporate once they pass, and tend to give the floor to the loudest voice. A well-written document, by contrast, can be read at each person's convenience, remains permanently, and, because it's in writing, records everyone's opinion equally.

Fully remote companies like GitLab explicitly adopt a "documentation first" culture. The core principle is "write the document before holding the meeting." Don't explain a problem for the first time in a meeting; share it as a document beforehand and run an asynchronous discussion as comments on that document. Hold a meeting only when real-time conversation is truly needed — when there is a disagreement that documents cannot resolve.

The benefits of asynchronous communication are clear.

  • It creates time to think deeply. Answering in writing produces organized thought rather than off-the-cuff reaction.
  • It is free of time zones and schedules. Essential for distributed teams.
  • It leaves a record automatically. The discussion itself becomes a document.
  • Introverts participate equally. Even those who can't find a gap to speak in a meeting can contribute fully in writing.

Asynchronous has limits too. Sensitive conversations tangled with emotion, fast brainstorming, and complex real-time negotiation are still better synchronous. The key is not one or the other but appropriate distribution. Information delivery and decision records by document; real-time agreement and relationship-building by conversation.

Document Templates: Skeletons You Can Use Right Away

Starting from a blank page every time makes writing a burden. Making templates for frequently written documents lowers the barrier and creates consistency.

Design Doc

# [Title] Design Doc

## TL;DR

- One-line summary

## Background / Problem

- What we're trying to solve

## Goals / Non-goals

- What this work will achieve / what it deliberately won't

## Proposed approach

- The core design

## Alternatives considered

- Alternatives A, B and why they weren't adopted

## Risks / Scope of impact

- Expected risks and mitigations

## Timeline / Next steps

- Who, what, when

Architecture Decision Record (ADR)

# [Number]. [Decision title]

## Status

- Proposed / Accepted / Deprecated

## Context

- In what situation was this decision needed

## Decision

- What we decided

## Consequences

- Positive/negative effects this decision creates

Meeting Notes / Async Decision

# [Date] [Topic]

## Conclusion (first)

- What was decided, at a glance

## Action items

- [ ] Owner — task — deadline

## Discussion

- Summary of key points

The purpose of a template is not to force a format but to remind you of "what not to leave out." Especially "alternatives considered" and "the reason for the decision" are the items people most often omit but that are the most valuable.

A Case: Same Information, Different Documents

Let's make the abstract principle concrete. Here are two versions of a document sharing a new deployment process.

Mode A — Author-centered "Last week there were some issues with deployment, so we reviewed several options; at first we thought about A, then looked at B, and after discussion we decided to introduce a new process. For details, see below..."

Mode B — Reader-centered "Summary: Starting today, deployment must go through staging. The only difference from the old way is that a 'staging approval' step has been added.

Audience: All developers with deployment permissions Effective: From June 19, 2026 Reason: To prevent recurrence of last week's outage caused by direct deployment

New process (3 steps):

  1. Merge PR
  2. Verify after automatic staging deployment
  3. Click the approval button -> deploy to production

If you only want to see what changed: step 3, the approval step, is new."

Mode B is superior because it arranges what the reader needs in the reader's order. Conclusion first, audience and timing clear, the change pinpointed. The reader can quickly find just the part they need and leave.

Pitfalls: Guard Against Over-Documentation

So far I've emphasized the value of documents, but balance is needed. Documentation is a tool, not a goal. Over-documentation is as harmful as under-documentation.

Pitfall 1: Documents no one reads

A document made for the sake of making one, a document to fill out a format, only incurs cost. Trying to document everything buries the truly important documents in noise. Before writing a document, ask: "Who will read this again, when, and why?" If there's no answer, don't write it.

Pitfall 2: Documentation rot

The most dangerous document is not the missing one but the wrong one. If the code has changed but the document stays as it was, that document actively misleads the reader. A document you can't maintain is better not written. That's why a light index document pointing to "where what is" often outlives a heavy document holding every detail.

Pitfall 3: Documents duplicating code

A comment or document that merely translates code into prose has no value. If the code already says "how," the document should focus on "why."

Pitfall 4: Paralysis from perfectionism

A 70% document is better than writing nothing while trying to write a perfect one. A document is a living thing and can be fixed later. "Sharing a draft" is almost always better than "private until perfect."

The balance point is this. Knowledge that is read often, used long, and would vanish if the person left — leave that in a document. Don't document what's written once and discarded, what's already obvious in the code, or what will soon change.

The Writing Process: Drafting and Editing Are Different Jobs

A good document doesn't come out in one pass. A common misconception among people who find writing hard is that they try to form perfect sentences in their head and write them down in one go. Then they get stuck on the very first sentence. Writing is two separate jobs. The first is pouring out thoughts (drafting); the second is refining them (editing). Trying to do both at once is the chief culprit that makes writing painful.

There's a principle writers often cite — the spirit of "write drunk, edit sober": draft fast and rough, edit cold and clear. In the drafting stage, forget spelling and sentence polish and just get everything in your head out. It's fine if the structure is a mess. You need raw material before you can refine.

The editing stage determines the quality of the document. When editing, read with the reader's eyes, not the author's. In particular, check the following.

  • Is the conclusion at the top, or does it appear only after reading to the end?
  • Are several thoughts tangled into one sentence (one sentence, one thought)?
  • Where would a first-time reader get stuck?
  • What filler could be cut without losing meaning?

That last one especially — "cutting what can be cut" — is the heart of editing. The French writer Saint-Exupery said, "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away." A good document is good for being short, not long. The reader's time is expensive, and filler steals that time.

One practical tip: before publishing, read it aloud, or let it sit a day and look again. Awkwardness and gaps invisible while writing become visible with distance. And if possible, ask a colleague, "Does this make sense to you, seeing it fresh?" The surest way to break the curse of knowledge is the eyes of an actual reader.

Where Documents Live: The Problem of Discoverability

No matter how well-written, a document no one can find is as good as nonexistent. The hidden half of documentation is "discoverability." Where the document is and how it's searched matters as much as the content.

A common failure is documents scattered everywhere. One person writes in the wiki, another in a Slack message, another in a personal note. As a result, the same questions repeat, and answers that already exist get rebuilt because no one finds them. Duplication and contradiction of information pile up.

The practice of raising discoverability looks like this.

  • Decide on a single source of truth. An agreed place where "this topic lives here."
  • Write searchable titles. Put the words people will actually search into the title.
  • Keep an index document. A light hub document pointing to "what is where."
  • Link related documents together. So finding one leads to the adjacent ones.

Here the problem of "stale documents" mentioned earlier returns. A document that searches well but has wrong content is the most dangerous. So discoverability and freshness must go together. For old documents, it's good to state "Last updated: date," or, if no longer valid, explicitly mark them "archived."

A Hidden Benefit: Writing Organizes Your Thinking

Seeing the value of a document only as "conveying to others" misses half. The act of writing a document is itself a powerful tool for organizing thought. That is, a document benefits not only the reader but the author.

When you try to actually write down something you felt you knew in your head, you get stuck all over. "Oh, I didn't actually understand this part clearly," "there's a logical leap between these two steps." Writing mercilessly exposes the holes in your thinking. You can gloss over things in speech, but writing permits no glossing.

You could call this "writing is debugging your thinking." Vague thoughts become vague writing. If the writing won't become clear, that's usually not a problem of writing skill but a signal that the thinking isn't clear yet. So writing a design document before moving the design into code surfaces many of the problems you'd meet in implementation in advance.

This is why Amazon has people write six-page narrative memos instead of slides in meetings. Jeff Bezos said written narrative "forces you to think more clearly." Bullet points can hide gaps in logic, but a narrative in full sentences exposes those gaps.

So don't regard a document as "an unavoidable side chore." Writing even one page before starting something important is, before it's for others, a way to make your own thinking clear. Often, in that process, a better direction that was invisible before you wrote comes to mind.

Frequently Asked Questions (FAQ)

My writing is too slow. It takes me half a day to write one document.

Usually it's because you're trying to draft and edit at the same time — polishing one sentence to perfection and unable to move to the next. Pour everything out roughly first, then refine. Another thing: don't start from a blank page every time; use a template. And not every document needs the same level of effort. Investing deeply only in documents that will be read often, and writing one-off notes lightly, is the discernment that saves time.

A meeting is faster, so why bother writing a document?

A meeting is fast in the moment. But it evaporates. It doesn't reach the person who wasn't there, the person who forgot a week later, or the person who joined six months later. A meeting is fast only for "the people present right now." Documents are better for decisions and information delivery; meetings are better for real-time agreement and discussion. The best combination is "share context by document before the meeting, decide in the meeting, record the decision by document after."

I write documents but no one reads them.

Check three things. First, is the conclusion at the top? If the core appears only after reading to the end, people leave midway. Second, can it be found? It may be a discoverability problem. Third, is the document really needed? If no one reads it, maybe it didn't need to be written in the first place. An unread document is often a problem of structure or location, not content.

If I add lots of comments to the code, don't I not need documents?

Comments and documents play different roles. Comments are good for the close context of "what this code does," but it's hard to capture the big picture like "why this system was designed this way" or "what alternatives were considered." Also, comments reach only those who read the code. Decision-makers and new hires don't read code. Code comments are the close context of "how," documents the big context of "why" — you need both.

Document Writing Checklist

Before publishing a document, check the following.

  • Can you tell "what the document is about" from the first line?
  • Is the TL;DR or conclusion at the very top?
  • Is the "why" written (not just the what)?
  • Could a first-time reader understand it (curse-of-knowledge check)?
  • Did you expand abbreviations and jargon?
  • Is the structure visible from skimming alone (headings, lists, tables)?
  • Is the reader's next action clear?
  • Did you write down alternatives considered but not adopted?
  • Can someone still maintain it six months from now?
  • Will someone really read this document again (or would a meeting have been better)?

One More Thing: The Power of Diagrams and Tables

Long prose isn't always best. Some information is understood far faster as a picture or table than as text. "A picture is worth a thousand words" applies to documents too.

Visualization is especially powerful for the following.

  • Structure and relationships: system architecture, data flow, dependencies between components — one diagram replaces three paragraphs.
  • Comparison: the pros and cons of several options come across at a glance when placed side by side in a table.
  • Order and steps: a process or procedure is clearer as a numbered list or flowchart than as prose.
  • Time flow: a schedule or change as a timeline.

Visualization has pitfalls too. First, maintenance cost. Pictures are more cumbersome to fix than text, so they tend to be neglected even when content changes. So for frequently changing content, prose is sometimes better. Second, the trap of polish. Don't let making a pretty diagram steal the time you should spend on content. Even a rough hand sketch is enough if it conveys the core.

The core principle is "choose the format that fits each kind of information." Don't write everything as prose, nor draw everything as pictures. Structure as pictures, comparison as tables, context and reasons as prose — choosing the vessel that fits the nature of the information is another way to consider the reader.

Closing: A Letter to the Future

Return to that wiki document at LINE. The reason the departed colleague's document stayed in memory so long is not merely that it was well written. It is that you could feel he wrote it thinking of the time after he was gone, with consideration for a future colleague he had never met.

To write a document is to help people across time. By spending 30 minutes now, you save someone half a day of floundering six months from now. Even where the author is no longer, the writing keeps working.

A good document need not be fancy. It only needs to be read again. Put the conclusion first, leave the why, consider the first-time reader, and write only what's truly needed — that is the whole of writing that gets read again.

And remember. Leaving something now, even at 70%, is almost always better than leaving nothing while waiting for a perfect document. A document is a living thing, and the next person can fix and add to it. Writing the first sentence is the hardest part. Once you start, thinking organizes itself by following the writing.

The document you write today will speak on your behalf even after you've forgotten it. So write a kind letter to the future reader. That reader includes you, six months from now.

References

Discuss on Twitter • View on GitHub