You need to sign in or sign up before continuing.
Reflection — An Honest Take 8 min

Honest Take — Before You Begin

Honest Take — Module 6: Writing for Learners — From README to Body of Work #

This module asks for two transformations and they fail in different ways, so I want to take them separately. The artifact-level one first. The re-engineering exercise will take three to five times longer than you expect, and the gap between "this should take an afternoon" and "this took the entire weekend" is where most engineers quit. The reason for the gap is the thing the exercise exists to teach you: most of your existing technical writing is record-keeping, not teaching. "Here is what this library does" is record-keeping. "Here is the gap most teams have, here is how this closes it, here is the five-minute verification that it worked" is teaching. The vocabulary is similar; the cognitive load on the reader differs by an order of magnitude; and the rewrite is slower because you are now writing for the reader's cognition instead of your own retrieval.

When you run the reader test on the before and after, the feedback will be slightly more brutal than you expect — a place where the original assumed context you genuinely could not see, a missing transition, an example without the abstraction after it. That feedback is the module's gift, and Diátaxis is the single most useful rubric for acting on it: most documentation fails by trying to be tutorial, how-to, explanation, and reference on the same page.

If you maintain a package with real traffic, the README is the obvious candidate — largest audience, longest half-life, and over twelve to twenty-four months a re-engineered README produces things most engineers under-weight: better issue quality, fewer redundant questions, and a steady trickle of inbound from people who read it and concluded "this person teaches well and probably engineers well." That trickle is career capital you cannot buy any other way.

Now the practice-level transformation, because a single brilliant artifact is not a body of work. Most engineering blogs fail, and I want to be specific about how, because the failure modes have been stable for a decade: a brilliant post, a small spike, then four months of silence. A 600-word idea padded to 2,000 words because that is the apparent shape of a Real Blog Post. A home built entirely on a rented platform, then surprise when the platform's algorithm or paywall changes who gets read. Paralysis induced by reading writers far more practiced and internalizing their level as the floor. No recognizable voice — every post a careful neutral encyclopedia entry by a slightly different person. Notice that none of these is a writing-quality failure. They are all process failures, and the fix is process: cadence beats brilliance, and it isn't close. Twelve mediocre-but-genuine posts in a year outperform two transcendent posts and ten months of silence on every metric that matters — search, trust, your own development, the back catalog. On a busy week, choose cadence. The brilliant posts come from the practice of having to produce, not from waiting.

The calibration set is dangerous and I want to defuse it in advance. You will read Julia Evans, Dan Luu, Tanya Reilly, Patrick McKenzie, and feel the brief ugly thought: "I'm not as good as them, so why publish at all?" Wrong three ways. They were not that good when they started — the early archives have rough edges. The reason they are that good now is volume; they have published more posts than most engineers have read. And your readers have mostly never heard of them — they are reading you because your topic matched their problem today. Comparing yourself to writers your readers haven't found is a form of self-injury. Study the form; refuse the comparison.

On platforms, the two earlier drafts of this curriculum genuinely disagreed: one treated an existing hosted-platform blog as a surface to audit and improve in place; the other insisted the canonical home be a domain you own, full stop. The merged edition resolves it the right way — audit what you have, but build the canonical home on your own domain, and use hosted platforms as syndication. The disagreement was really about time horizon. In any given year, the rented platform is fine. Over a decade, every rented platform changes shape — the pattern has repeated roughly every five years on every platform — and the writers who treated rented as home watched their distribution reprice overnight. A blog at your own domain, even ugly, even with fifteen readers, is the real asset. This decision costs almost nothing now and is expensive to retrofit later, which is exactly the profile of decisions engineers respect everywhere except, apparently, here.

Conclusion #

Two transformations: the artifact that teaches instead of records, and the practice that compounds instead of bursting. Re-engineer one piece with M1's science, M3's outcomes, and this module's prose discipline, and test it on a real reader. Then commit a cadence you can sustain, on a domain you own, at the length each post earns. Process beats craft in a tie, and most blogs lose on process.

Predictions #

  • The first re-engineered piece will take three to five times your estimate. Budget the gap instead of fighting it; the slowness is the cognitive-load shift happening.
  • Your reader test will surface at least one assumed-context failure you genuinely could not see. If it doesn't, your reader was being polite — find a blunter one.
  • You will feel embarrassed by your second post when you finish your fifth. Do not take the second post down; it is part of the trail, and the trail is the practice working.
  • You will fall off cadence at least once in the first year, probably between months four and eight. The skill is not avoiding the fall; it is time-to-recovery. Never silent more than six weeks.
  • Within six months, one topic will recur in your posts despite no plan to make it your beat. That is your beat. Lean in.
  • Diátaxis will become the most-used mental tool from this module — you will start classifying other people's documentation by quadrant within weeks, including documentation you wrote.
  • If you re-engineer a high-traffic README, within twelve months you will receive at least one piece of inbound — a job conversation, a consulting inquiry, a conference invitation — that cites it. Inbound lag is long; the half-life is longer.