Get AI summaries of any video or article — Sign up free
[Lightning Talk] Julia Evans - Can we (sometimes) go back to print documentation? thumbnail

[Lightning Talk] Julia Evans - Can we (sometimes) go back to print documentation?

Write the Docs·
4 min read

Based on Write the Docs's video on YouTube. If you like this content, support the original creators by watching, liking and subscribing to their content.

TL;DR

Print documentation is most effective for foundational topics that are unlikely to change for years, not for rapidly evolving surfaces.

Briefing

Print documentation can still be a smart choice when the subject matter is stable—especially for foundational concepts that won’t churn as fast as APIs and tooling. Julia Evans, who runs a solo publishing company that turns large technical topics into compact 24-page comics, argues that the “everything changes every week” reality of modern software doesn’t invalidate print so much as it narrows where print works best. The key is selecting material that is core and durable: Unix permissions, the most important API endpoints and how they relate, or other product fundamentals that have historically stayed true for years.

Evans’ central test is practical: when documenting something intended for print, aim for topics that are unlikely to change for at least three years. That doesn’t mean ignoring change entirely—it means recognizing that not everything in a technical ecosystem is moving at the same speed. Many systems have layers where compatibility is built in, and those layers are ideal candidates for print. In container technology, for example, the surrounding ecosystem may feel “frothy” and fast-moving, but the core mechanics are implemented in the Linux kernel, which benefits from backwards-compatibility guarantees. The result is that key container behaviors are comparatively resistant to sudden redesign, making them suitable for documentation that can be handed to someone and still hold up later.

The same logic applies to protocols. The HTTP protocol’s fundamental behavior is not expected to shift dramatically anytime soon, so documenting it in a durable format can remain useful long after publication. Evans also highlights a documentation advantage that comes from focusing on stable components: it becomes easier to identify the parts that matter and the interactions between them. Instead of chasing every minor variation, documentation can emphasize the key relationships—such as how components communicate during a system call—often using diagrams or comics to show message flow between parts.

That stability unlocks a second benefit: time. When the content is unlikely to change, authors can invest more effort into clarity and completeness, producing documentation that genuinely helps readers over the long term. Evans describes receiving feedback that printed materials feel personal—like they were drawn by hand, printed, and given directly to the reader—creating a break from the constant noise of online information. In her view, print isn’t a replacement for digital documentation everywhere; it’s a targeted tool for capturing the parts of computing that are meant to last.

Cornell Notes

Print documentation works best for technical topics that are stable enough to remain accurate for years. Julia Evans recommends choosing fundamentals—like Unix permissions, core API endpoints, and foundational protocol behavior—rather than fast-changing surfaces such as frequently updated parameters. She points to Linux kernel backwards-compatibility as an example where container internals are comparatively durable, and to HTTP as a protocol whose core behavior is unlikely to change soon. By documenting stable components and their interactions, authors can spend more time producing high-quality materials that readers can rely on long after publication. Print also offers a tangible, human feel that contrasts with the constant churn of online content.

What criteria does Evans use to decide whether something should be printed?

She favors material that is unlikely to change for at least three years. The goal is to document parts that are “core and foundational,” such as Unix permissions or the most important API endpoints and how they relate, rather than areas that churn weekly. She notes that many tech products contain sections that effectively never change once learned, and those are the best candidates for print.

Why does print make sense for containers even though the ecosystem feels fast-moving?

Evans distinguishes between the surrounding ecosystem and the underlying core mechanics. While container tooling and ecosystem details can change quickly, the core behaviors are built into the Linux kernel. Because the kernel provides backwards-compatibility guarantees, the fundamental container workings are comparatively resistant to change—making them suitable for durable printed documentation.

How does Evans connect print documentation to protocols like HTTP?

She argues that HTTP’s fundamental behavior is not expected to change anytime soon. That makes it an appropriate target for print, where accuracy over time matters. The same principle applies: document the stable “how it works” layer, not the transient implementation details.

What documentation technique does Evans recommend when the subject is stable?

When the main pieces don’t change, it becomes easier to identify components and illustrate key interactions. She mentions using diagrams and comics to show message flow between components—for example, depicting what happens during a living system call—so readers can understand relationships, not just isolated facts.

What practical advantage does stability give authors and readers?

Stability lets authors invest more time in producing “really beautiful” documentation because readers can keep using it for years. For readers, it creates a sense of reliability and also a more personal experience—printed materials can feel hand-drawn and directly given, offering a break from the overwhelming, constantly updated world online.

Review Questions

  1. Which types of technical knowledge are most suitable for print documentation according to Evans, and why?
  2. Give one example Evans uses to show that a fast-moving ecosystem can still contain stable fundamentals. What makes those fundamentals durable?
  3. How does Evans’ approach to documenting stable components (e.g., showing interactions) differ from documenting constantly changing details?

Key Points

  1. 1

    Print documentation is most effective for foundational topics that are unlikely to change for years, not for rapidly evolving surfaces.

  2. 2

    Evans recommends targeting material expected to remain accurate for at least three years.

  3. 3

    Stable product layers—like Unix permissions and core API endpoint relationships—can be documented once and remain useful for long periods.

  4. 4

    Container internals are a good print candidate because core behavior is implemented in the Linux kernel, which offers backwards-compatibility guarantees.

  5. 5

    Protocols such as HTTP are suitable for print because their fundamental behavior is not expected to shift dramatically soon.

  6. 6

    Focusing on stable components makes it easier to map key interactions and message flows, often using diagrams or comics.

  7. 7

    Durable print enables deeper author investment and gives readers a tangible, human-feeling alternative to constant online churn.

Highlights

The “everything changes” problem doesn’t kill print documentation—it just means print should target the parts that don’t change.
Linux kernel backwards-compatibility helps make container internals a durable subject, even when the broader container ecosystem moves quickly.
Documenting stable components lets authors spend more time and readers keep using the material for years.
Comics and diagrams can capture component interactions (like message passing during system calls) in a way that stays accurate over time.

Topics

  • Print Documentation
  • Stable Fundamentals
  • Linux Kernel
  • HTTP Protocol
  • Container Internals

Mentioned