Lessons
Some things worth knowing
One idea each, and something you can try in about five minutes. They build on each other, so the first one is the best place to start, but nothing stops you jumping to the one that sounds like your week.
If you want the longer arguments instead, those are the field notes.
- Your AI doesn't read your article. It reads a piece of it.The unit that matters isn't the page. It's the passage, arriving on its own with nothing around it.
- Where your AI got the wrong idea about youThree different sources, three different fixes, and only two of them are yours to solve.
- The property most documentation failsNot findability. Quotability, and careful writers fail it more than careless ones.
- The question that decides what kind of article to writeMost articles fail because somebody wrote the wrong kind, and the test is one question long.
- Why "one name per thing" got expensiveMachines don't shrug. And drift isn't the dangerous part.
- Not everything you're asked to document should be documentedA documentation backlog is a symptom list, and writing the article buries the evidence.
- Your style guide is now a system promptThe reason to have one changed, and so did the reason most of them fail.
- Why you never find out whether your docs workedDocumentation has no error log, so the loop has to be built by hand. Here's the smallest one that works.
- Your help center goes wrong slowly, and then all at onceNothing breaks on the day the product changes. It breaks the first time somebody trusts the old answer.
- The fact hiding in your screenshotIf the only place you say where a setting lives is a picture, then to anything that can't see pictures, you never said it.