Notes on every command, so I'd remember why I added it

By 2019 I had a few hundred commands saved in TerminalNexus, sorted into projects and categories. That was the problem. I would open a project I had not touched in months, look at one of my own commands, and have no real idea why I had written it that way. What was that flag doing there? Why two commands chained onto one button instead of run separately? Past me knew. Present me was guessing.

So version 1.4, in the summer of 2019, added something plain: notes. Not a separate document I would never open again, but a note attached to the command itself, right where I run it. A line or two on what it does and why it is there. The kind of thing you swear you will remember and never do.

I added project-level notes in the same release, for the stuff that is about the whole project rather than one command. Setup steps, which server a project points at, the gotcha that bit me last time, anything true of the project as a whole. It sits on the project screen, so it is the first thing I see when I open one.

This came straight out of my day job. I work across more command line tools than I can keep straight, and a lot of what I run there are commands I touch a handful of times a year. Those are the ones that go fuzzy. The daily ones stick. It is the quarterly one, the once-in-a-while one, the only-when-the-build-breaks-this-exact-way one that you later read like a stranger wrote it.

Writing the note in the moment I made the command turned out to be the whole trick, while I still knew what I meant. By the time you think you should document something, you have usually half forgotten the part that was worth writing down.

Later, in 2.0, I let the notes carry rich text instead of plain. A small thing, but a long note in one unbroken block of text is its own kind of useless.

None of this is clever. It is the least glamorous feature I have ever been glad I shipped. And if a command in there is cryptic enough to need a note and does not have one, well, I know exactly who wrote it that way:)

Thanks for reading. If you have a folder of scripts you no longer understand, you have my sympathy. Go write yourself a note, and send me a line if it helps.