From Shkspr · · 1m 10s
I paid people to try and follow my README
Terence Eden paid real users €25 each to test his README file and fix biases.
In brief
Terence Eden paid real users €25 each to test his README file and fix biases. Terence Eden paid people €25 to test his README file and found it confusing for users. Originally reported by Shkspr.
Developers struggle with documentation
Developers often write confusing documentation that users find hard to follow.
“We like to say RTFM but often there ain't no FM to R”
I tested my README with real users
I paid people €25 each to test my README file and get feedback on the first-run experience.
“I was prepared to pay them €25 for an hour of their time”
Users spoke aloud while testing
Volunteers shared their screens and spoke aloud to explain what they did and what confused them.
“Tell me what they were doing”
Key issues found during testing
The link to the demo tool was wrong, some users read READMEs in the terminal, and file renaming was confusing.
“The link to the demo tool was wrong”
I updated the README after each test
After each session I updated the README based on what people found difficult and re-tested it with the next person.
“After each session I updated the README based on what people found difficult”
Real users improved the README
Terence Eden paid out around €150 to have people criticise his README file and make it easier to follow.
“In total, I paid out around €150 to have a bunch of people criticise me to my face”
What matters most
Terence Eden paid people €25 to test his README file and found it confusing for users.
