Don't use an LLM for your README.md

Don't use an LLM for your README.mdAndrew Quinn's TILsAdd me on X / Twitter! You can cite this post as a reason if you're shy. One of my more popular open source projects is Shell Bling Ubuntu, which, contrary to its name, actually supports many different operating systems these days: modern macOS, Alpine, Fedora 40 and up, Rocky Linux 8 and up, WSL (Windows Subsystem for Linux), and so on. But while I feel the project is in a much more advanced state than it was four or five months ago after all that hardening and robustness work, I haven’t seen much extra marginal uptake or additional stars on GitHub as a result. I think the reason is actually quite simple: I replaced the README with a much drier one, driven by LLMs (Large Language Models), and people (correctly!) read that as a negative signal of care compared to the previous one.1 Here is the old README.md, all hand-authored. Technically speaking, it documents an objectively worse version of the code. You need to run three or four commands, not one. I didn’t check SHA256 (Secure Hash Algorithm, 256-bit) sums, which maybe wasn’t such a big deal for a personal setup script that got popular in 2023, but it sure is a big deal in Supply Chain Hell 2026.2 You need to close and reopen your terminal! Several times!! On and on the list goes. But it has personality, and that doesn’t show through nearly as well in the new README.md. The new one is&mldr; dry. There’s no video.3 There are no odd little jokes or flashes of inspiration from yours truly. The point of the project is to make using the shell a joyous act for developers mostly on the newer, younger side of things. The new README instead feels like I wrote it for, say, the Operational Technology folks I talk to at my day job, who actually care4 about things like risk management and say words like “procurement” with a meaning behind them. I consider this a misstep as a steward of this tiny convenience project of mine. When I have some time I think I’ll step through the README.md and try to make it more obvious why Shell Bling Ubuntu might make your terminal-going life more fluid and fun. This is in reference to the economic study of signalling theory . A signal only carries information if it is expensive to fake. The male peacock’s mesmerizing tail of evil eyes works precisely because a sickly peacock cannot grow one. A charming, well organized, slightly dry README used to be exactly that sort of costly signal; it meant some collared-and-tan-khaki’d engineer with an interest in technical writing had sat down and spent an evening caring about you, the reader. Why would they do that if they didn’t have a good enough product in the first place? Then with the advent of LLMs, the cost of generating competent prose fell through the floor - which by and large is a very good thing. There are many professions where being unable to write well is not a killer to the profession, but significantly increases the perception of professionalism and amounts one can charge for it, because it provides actual value, not just signaling value. Handyman work is my goto example; my father is an electrician, and would often ask me on Saturdays to fire up Microsoft Word and later Google Docs to write out invoices for his clients, because I had a more precise command of written English than he did. I knew enough about his work to ask him the important questions that a well-educated but not technically inclined Boston homeowner might reasonably ask, and we could put that information on the bill, because I knew my dad took great pride in his work and didn’t cut corners. But I also charged him a few bucks per invoice for the hour. If you don’t have a literary son to rely on, you can easily imagine how much an actual adult might charge for the same service. And you can imagine why many sole proprietorships might say, “Uh&mldr; no thanks. I’ll make do.” The extra money and demand they might generate from being good at writing invoices is still marginal compared to the costs of looping in a whole extra human being to write them. Any-way, when LLMs came online, and people started to learn how to use it, suddenly this got a lot cheaper, and the actual value of a well written invoice remained, but the signal went out the door. Where did the signal move to? I posit it moved in much the same way the authenticity of music became big in the late 20th and early 21st centuries: to intentional human erratic weirdness, to in-jokes, to a screen recording of the author fumbling a command and leaving it in. These are now the expensive things, because they are precisely the things a model will smooth away by default. The market for boring legible sincerity is tightening every year as a result of being machine writable - send some flowers to e.g. your friendly neighborhood accountant for their loss. ↩︎

The xz-utils backdoor is a famous one and makes for gripping...

Don't use an LLM for your README.md

Related Articles

(no title)

Scientists reverse brain aging, with a nasal spray

NHS apologises and admits Palantir have access to identifiable patient data

AI has torched the market for junior programmers

Al Vigier: Canada's AI strategy shouldn't include secret Palantir bills