I paid strangers €25 an hour to break my README
I paid people to try and follow my README
Developers write documentation blind to their own assumptions, so Terence Eden paid volunteers €25 an hour to install his ActivityBot software while narrating every confusion out loud. Across several sessions and roughly €150, they caught a broken demo link, unexplained terminology, baffling file-renaming steps, and jokes that only confused people. He updated the README after each session and re-tested it on the next person.
In total, I paid out around €150 to have a bunch of people criticise me to my face. Hey, cheaper than therapy, right?
- piro0919
I half agree.
I build apps with Claude Code, and I test them by having the AI click through the UI with Playwright. That's enough to check that things work as specified and nothing is broken.
But I think the purpose is different when an AI tries it and when a person tries it. To put it in extreme terms, AI is for UI and people are for UX. People find UI problems too, though: in my music player, songs got blocked from playing in Safari on a real iPad, and I only found it by using it myself. The things found in this article, like the jokes that didn't land or not knowing what the tool even does, are on the side only people can find.
(I wrote this in Japanese and used AI to translate it.)
- bambax
> 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.
I sometimes write readmes for myself, so that I can remember the exact steps to generate a data report, etc.
It's surprising how much they become incomprehensible after just a couple of weeks; when everything's in our head it's all clear, fluid and self-explanatory; but once we have forgotten the context, nothing makes sense anymore.
- andai
>I hadn't actually explained what the software would do.
Half the posts I see lately are like, "Gleam 2.0. What we learned" and then you go to the homepage and it's "Gleam is a Tribble for your Fork! (Scroll down) See if you qualify for Gleam Enterprise!"
- 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.
- extralongdivisi
> I hadn't actually explained what the software would do.
I cannot tell you how many READMEs I've read that follow the pattern: "<uninformative-name> is a <buzzword> <buzzword> written in <language>." I only have some semblance of what it does after using/seeing a demo; too often one that isnt available through the README.
- legacynl
I love this. Most readmes are plain bad. I think the most egregious is when a readme doesn't state what the project does. I get that not every project is aimed at the public, but if you go through the bother of creating a readme file, why not go the extra 10 centimeters by writing the most basic information?
Other issues:
* outdated (and thereby wrong) information
* using un-introduced abbreviations (bonus points for abbreviations that have common meanings, e.g.: EG, NB, IE, ETC)
- trollbridge
This is one of those things LLMs are really good at.
Create a new container or sandbox, copy in the git repo or point it at your staging docs, and see what happens.
- pinkmuffinere
> My jokes aren't funny and are actively confusing.
:’)