I paid people to try and follow my README

commandersaki

I hate READMEs with a gazillion emojis, too much noise.

coo1estguy

This used to be called "I hired QA people to identify gaps in my project", but hey now it has become paying people to follow readme

WhyNotHugo

There's a zeroth step missing from both the Quickstart and Full Set Up: install php-fpm, configure it, and configure your http server to serve using it as a backend. It seems to be taken for granted — that's something you'd already have in place if you're already serving applications in PHP, but would have to figure out on your own if you haven't served anything in PHP so far in your life.

chanux

> My jokes aren't funny and are actively confusing. I used to write technical documents in prose style, sometimes with meandering stories. I guess I picked it up from my early blogging days. I realized I hated reading some of them back. So I tried to keep it cut and dried. I do sometimes sprinkle a bit of colorful wording just to add a bit of humanity but only if it doesn't get in the way of the main message.

ozlikethewizard

"They were the ones who caught the mistakes that no spell chequer could." Nice, good article lol. I appreciate a joke or two in a readme but totally understand the annoyance, I think forgetting to actually say what the software does is super common as well though. Often trying to figure out if something found on github will actually solve a problem only to be met with a list of install commands.

Neywiny

Yes. The amount of projects that don't just run is outstanding. Luckily docker container projects are inherently better at this is in terms of dependencies, but there are still often weird assumptions or medical incantations to get them during.

scriptsmith

Somewhat related question: what is it about READMEs that AI agents love to dump the most useless, hard to contextualise & comprehend, irrelevant rubbish into them that makes understanding a project and onboarding so hard? It feels like like the AI agents can't help themselves sometimes, and the judgement exercised around what's included and omitted is baffling. But maybe READMEs have always been this bad, and AI agents have raised the baseline?

badsectoracula

> I know someone is going to say "why not just ask an LLM to simulate a range of users?" The answer is very simple - I want to speak to real people. People are brilliant! They can make you laugh, you can see their cat when it wanders on to the call, they bring a unique perspective to the problem, and they're really happy when you give them a €25 voucher. Some will gladly do it for free and make you happy! So what the author actually paid for was to interact with humans and the README checking was secondary - because, really, my own first thought was literally to ask an LLM check and try to follow the instructions in the README and pretty much any decent LLM (including several local ones) would be able to check if they're adequate and even suggest improvements (just don't let them write it for you :-P).

shevy-java

Writing good documentation is difficult. From those who say "the source code explains everything", I think 80% are too lazy to write documentation in the first place. Having said that, I found consistently that when a project has working examples, ideally documented a bit, aka explained, they tend to work much better than those projects that have no examples. Working examples often also help get into a project quickly and check out how it works. It helps to learn too. READMEs are not useless, of course, but the quality varies a lot. I also know of folks who use AI slop spam to improve it, but while it may improve a little bit, it generates a lot of horribly to read text that makes no sense. I am noticing this with the ruby core dev team - they (almost) all suddenly have perfect language skills but it is more like an advanced babelfish translator. What they piece together here makes no sense. Claude in particular is now famous for this slop content. And I don't understand what it is used: real people read any of this AI slop? Because I just skip it or filter it away these days.

simonbarker87

Most documentation reads like you should already know what you’re doing, which makes sense because it was written by someone who already knows how to do the process. I think good technical writing requires the same skills as good product ownership, that is empathy for the user and their perspective. Often technical writing is an after thought and not someone’s whole role and it really shows. Good article

astura

>But it is really hard to ignore your own biases. Of course you know that certain commands require sudo and obviously when you wrote -foo you meant --foo and everyone knows that you have to reboot afterwards. For God's sake, this is not "biases," wtf?? That's straight up just not reading/following the document you're supposed to be testing/reviewing. When I test my documents I actually follow them exactly, step by step, and I always catch these sorts of mistakes. Always. I always copy/paste commands because I know that is what the customer will do, so I have to make sure that works flawlessly. Dude, if you actually follow your own document, you don't have to pay people to do it for you. Also, you can make sure the person you are paying doesn't ignore the document like you apparently do. I stopped reading, I'm not interested in whatever else this dude has to say. I'm literally flabbergasted. Maybe it's because my documents have always gone to real paying customers who have to get through this install, and not some hobby project I'm super proud of or whatever and I don't think I'm super clever? Idk.

bgolson

Excellent article! Thank you for the reminder that I need to be spending more time with users… or hirelings :)

theletterf

Besides emojis, I find it too long. READMEs should be succinct and be like a switchboard to other docs (much like LLMS.txt tries to be for agents). Also, it features an FAQ. FAQs are problematic (as in not often effective): https://passo.uno/what-the-faq/ Edit: Clarification

prologic

And did it work?

sshine

Nix. I know, I know: It's complicated. But have you heard of AI agents? But I just onboarded 4 interns on a project where all they had to do was 1. Install the Nix package manager 2. Install direnv, enter the project repo, and `direnv allow` 3. Toolchain, git hooks, MCP servers, in-repo issue tracker, everything is available Our project manager requested information that was available in the issue tracker. I told her, she could get all her answers by asking our agent, and it'd automatically reference the issue tracker. I figured I'd just need to show her how to install the Nix package manager. But no, she already had it because another project by another team depended on it. Putting wrong information is README is so outdated when you have programmatic setup of your entire toolchain.

bryanhogan

This is very close to what you call usability testing in the field of UX design. The Nielson Norman Group has a good introduction to this: https://www.nngroup.com/articles/usability-testing-101/ Is this interesting to people on HN? I majored in a mix between coding and design.

rapnie

I know there are some great README's (and other documents) around, that document best-practices or templates for great README's. I found one that looked very useful and would've sworn I starred the repo to find it again in time of need. Alas, can't find it. Anyone has some good resources to point to, to add to this thread? Update: Found some related HN threads (omitted link-rotted submissions). - I'd like to review your README https://news.ycombinator.com/item?id=26842191 (91 comments) - Readme.so – Easiest Way to Create a Readme https://news.ycombinator.com/item?id=27006740 (65 comments) - Readme Driven Development https://news.ycombinator.com/item?id=1627246 (57 comments)

sccxy

Most README files should include a screenshot. Even if it is a command-line tool, a screenshot helps provide a better understanding of what to expect.

alaudet

Documentation is so important. I have been treating documentation in the same way I handle code. I found mkdocs works pretty well and integrated with a github job that updates the docs when I commit changes to my main branch. It also allows contributors to correct errors or add helpful instructions to documents. I think I have not paid enough attention to my biases though and like the idea of hiring someone to go through the process. I think my instructions are sound but maybe not so much for a user who is not as familiar as I am. I may not be doing things the optimal way but I have used a lot of documentation over the years and feel what I have done addresses gripes I have had with "Big Tech" provided docs.

dawnerd

Given the agents.md I’m assuming the readme was just spit out by an LLM and the goal was to not read as LLM text. Problem is, it reads like you prompted it to be written in more simple language. I just find it a bit misleading that you’re saying you want to talk to real people all while trying to clean up AI slop.