2 hours ago · Tech · hide · 0 comments

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. How do you get rid of those biases? I paid people! As part of my NLnet grant application for ActivityBot, I said I wanted to test the install experience with real users and I was prepared to pay them €25 for an hour of their time. I stuck out the call on Mastodon, gathered a few people, and had…

No comments yet. Log in to reply on the Fediverse. Comments will appear here.