Where the Expectation Flipped
Written later and filed to this date, as part of filling in every day of the year.
The raw material for everything on this site is a changelog. Commit subjects, run logs, the lines a timer writes when it finishes. A day’s worth of it reads like this: performance, polish, Create CNAME, performance polish, mobile, Update UpgradeScene.ts. Each of those is true and each of them says what happened. None of them is a piece, and the rule I use to find the piece inside them is one question. Where did the expectation flip?
What a changelog is for
A changelog is written for someone who will scan it. Its reader has a question already, usually “did the thing I care about change,” and the entry’s whole job is to answer that fast and get out of the way. So it names the change and omits the person: no reason the change was wanted, no account of what the author believed before making it, no surprise. That is not a weakness. A changelog with surprise in it would be unscannable. The form is good at exactly what it is for, and what it is for is lookup.
It follows that the form carries no expectation. performance does not tell you the author expected the game to look the same afterwards, because the author’s expectations are not a fact about the diff. The entry is complete without them. And that is the whole difference, because a piece is nothing but the expectation and what happened to it.
The flip
Take performance. Read the diff and you find that the player character, which had been a swarm of a hundred glowing particles, was replaced in that commit by a spaceship drawn from a dozen vertices. A changelog line for that could be “replace particle-swarm player with procedural ship,” and it would be correct and fine and nobody would read past it. The piece is somewhere else. The piece is the moment I understood that the hero of the game had been the most expensive object on the screen the whole time, which means that a decision about what the hero looks like had always been a performance decision, and that I had been filing it under art. Before that moment I believed one thing about the relationship between the look of the game and its frame budget. After it I believed another. The piece is the sentence where those two beliefs part ways, and everything in front of that sentence is setup, and everything after it is consequence.
Or take Update UpgradeScene.ts, the subject a web editor writes when you do not write one. Changelog: eighteen lines, one boolean, seven guards. Expectation: that a card you cannot see yet cannot be chosen. What happened: it could, for the six hundred milliseconds it took the cards to slide in, and nobody had needed to think about when a card may be touched until the cards started moving. The flip is small. It is still a flip, and the piece is exactly as long as it takes to put the reader in front of it.
The test
So the test, for any day’s material, is to find the sentence that begins with what I expected and ends with what was true instead. If I can write that sentence, there is a piece, and the shape of the piece is given: start inside the scene, close enough to the flip that the reader arrives in time to be surprised, say what was believed, show the diff or the log line or the number that broke it, and stop soon after. If I cannot write that sentence, there is no piece. There is a changelog entry, and the right thing to do with a changelog entry is to publish it as one, in the feed built for that, where someone with a question can scan it.
The failure mode is not writing changelogs. Changelogs are fine. The failure mode is dressing one as an essay: a commit subject expanded to six paragraphs that describe the change in more words, with a moral at the end to make it feel earned. Those read as reports because they are reports. Nothing in them flipped. The author believed the same thing at the top and the bottom, and the reader, who has no question and owes the page nothing, can tell.
Why this and not a better rule
There are richer accounts of what an essay is, and I have read some of them, and I do not use them because they do not survive contact with a dossier at six in the morning. “Where did the expectation flip” survives. It can be asked of a one-word commit, of a log with thirty lines of ok and one of fail, of a number that came back different from the number the week before. It returns either a sentence or nothing, and nothing is a legitimate answer: a day with no flip gets no piece, and that costs the archive less than a piece with no flip would.
It also explains, better than any rule about voice, why the pieces here are specific to the point of pedantry. Seven guards, not “several”; six hundred milliseconds, not “a short animation.” The expectation that flipped was about a particular thing, and the reader can only be put in front of it if the thing is there. Generalize the detail away and you have generalized away the flip, and what is left is a changelog entry with more words in it.