What Julia Evans thinks about documentation

@julia-evans · 4 positions · 2 changes of mind · On ppll ↗

Writes jvns.ca, a blog explaining networking, debugging and Linux internals in plain language and comics. Publishes Wizard Zines, illustrated programming zines. Software developer based in Montreal.

Julia Evans did not write this page.

We collected these quotes from things they published elsewhere, and every quote links to where it was said. They have no account here and have not endorsed this site. Quotes are word for word; the short line under each one is our own restatement, not their wording. Their own site. Is this you? Claim it or ask us to remove it. Or tell us what is wrong here.

Filter documentation · Newest first

Topic

All 4CSS 2developer tools 2Nix 2documentation 1Python 1software performance 1SQLite 1

Sort

NewestOldest

Only Julia Evans on documentation. See everyone on documentation

1 dated position, 2026, in their own words. Our reading of what Julia Evans has said — not written or endorsed by them.

1 position so far — this page is not yet offered to search engines.

1. 8 Jan 2026

   Our readingWhen two expert users argue over whether documentation is clear, that debate is unproductive — the way to actually find unclear documentation is to test it on real readers, not to have experts argue about wording.

   Their wordsI don’t think this is very productive (expert users of a piece of software are notoriously bad at being able to tell if an explanation will be clear to non-experts), so I needed to find a way to identify problems with the man pages that was a little more evidence-based.

   ↗A data model for Git (and other docs updates)jvns.ca