I paid people to try and follow my README
A developer shares their experience of paying real users to test their software documentation to overcome personal biases. The process revealed significant gaps in the README, leading to iterative improvements based on direct user feedback.
Why it matters
It highlights the importance of user-centric documentation and the limitations of relying solely on developer intuition or AI for technical onboarding.
ActivityBot ActivityPub developers · 1 comment · 700 words · Viewed ~225 times
Developers suck at writing documentation. We like to say RTFM but often there ain't no FM to R. At best we have a half-arsed collection of notes, some obsolete tips, and a link to a desolate forum full of people asking the same questions again and again. That's no way to treat our users.
I naïvely believe there's a better way. As I've written before, you should sit down and actually test your readme . Spin up a fresh Virtual Machine, go through what you've written, and see if it makes sense.
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.
Get smarter about the news
Sign up free for a feed built around what you actually care about, Dive Deeper research on any story, and the full text of every article.
Create free accountAlready have an account? Sign in