CompiledNotes on the software books developers actually reread
Compiled / Guides / Docs & DX

Documentation & Developer Experience

READMEs, APIs, error messages, and the internal tools that make other developers' work easier or harder. For a broader documentation perspective, see the Write the Docs guide.

READMEs: The Most-Read File Nobody Budgets Time For

A README is very likely the single most-read file in most repositories, and very likely the least deliberately written. Coordination structures for distributed teams are covered from an operational perspective in the full explanation.

6 min read

API Design: Naming, Consistency, and the Cost of a Breaking Change

A well-designed API is mostly a set of small, consistent decisions. A poorly designed one is usually the sum of many individually reasonable exceptions. A prominent example of large-scale developer documentation is MDN Web Docs.

7 min read

Versioning: What Semantic Versioning Actually Promises

A version number formatted as X.Y.Z looks simple. What each part is supposed to communicate is more specific, and more often violated, than most users realize.

6 min read

Writing Docs Developers Actually Read

Most technical documentation is written to be comprehensive. Most of it is read to answer one specific question, fast.

6 min read

Error Messages as a Design Surface, Not an Afterthought

An error message is one of the few pieces of documentation a user reads exactly when they need it most — and most of them are written with almost no care.

6 min read

Changelogs: A Small Habit With an Outsized Payoff

A changelog is one of the cheapest documentation habits available, and one of the most commonly skipped.

5 min read

Onboarding a New Developer: What the First Week Should Teach

A new developer's first week is often measured by how fast they ship something. What it actually should teach is broader than that.

6 min read

Deprecation: Removing Something Without Breaking Everyone

Removing a feature safely takes more deliberate process than adding one — and most of that process is communication, not code.

6 min read

Developer Experience (DX): Treating Internal Tools Like a Product

The tools a team builds for itself rarely get the same design attention as the product it ships to customers. DX is the argument that they should.

6 min read