I said state machine and lost people

I kept calling NOW.md a personal state machine.

I like the phrase. It is accurate. It is also the most technical thing I say about the least technical file in the whole method, and I said it for weeks without noticing what it was doing to people.

Two different reactions, and both are my fault.

If you are not a programmer, "state machine" sounds like something you install. It sounds like the part of the method where the free ride ends and the real setup begins. So you skip it, and you skip the one file that fixes the problem you actually have.

If you are a programmer, it is worse, because you know the term. You think I mean the thing from the libraries that model how an application behaves, transitions and guards and events. You go looking for the runtime. There is no runtime. You conclude I am overselling a text file, and honestly, from where you are standing, that is a reasonable read.

So Pillar 14 now says it in plain words instead.

A state machine means two things. There is a list of the states something can be in, and at any moment you can say which one it is in right now. Your project is in one state today. It is shipped, or it is half built, or it is waiting on somebody. NOW.md is where you write down which one, so nobody has to guess.

And then the line I should have written the first time: nothing here runs. It is a file you read.

Four lines. That is the whole change.

I am putting it in the log because the mistake is not really about jargon. I reached for the phrase because it made a plain idea sound like it had more engineering behind it. It does not need more engineering behind it. The idea is that a file which says what is true today is worth more to an agent than a year of decisions about what used to be true, and that idea is strong enough to be said in words a person can read once.

If I have to dress something up, I should be asking whether it is any good, not looking for a better word.