Developers suck at penning documentation. We akin to say RTFM but frequently there ain't no FM to R. At finest we have a half-arsed gathering of notes, several obsolete tips, and a nexus to a desolate forum complete of group asking the identical questions again and again. That's no way to treat our users.
I naïvely accept there's a improved way. As I've written before, you should sit downward and actually test your readme. Spin up a caller Virtual Machine, go through what you've written, and see if it makes sense.
But it is really difficult to disregard your own biases. Of way you cognize that certain commands necessitate sudo and evidently whenever 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 aid use for ActivityBot, I stated I wanted to test the instal cognition alongside genuine users and I was prepared to pay them €25 for an hr of their time. I stuck out the call on Mastodon, gathered a few people, and had a video call alongside them.
The format was simple. I explained that I was looking for feedback on the first-run experience. I knew that it wasn't ideal and actively wanted constructive criticism. I asked the unpaid to portion their display and, crucially, to conversation aloud. Tell me what they were doing. What they didn't understand, what confused them, what delighted them, what disappointed them, etc.
I took notes by hand (fuck feeding the machine) and spent multiple hours being told what incorrect assumptions I'd made.
Amongst the highlights I discovered were:
- The nexus to the demo tool was wrong.
- Some group peruse a README in the terminal.
- What does it really average to rename a file?
- How do you rename a hidden file?
- Should a demo tool be accessible on the web or fair the user's local machine?
- Why does several content explicitly need to be quoted and several not?
- My jokes aren't comic and are actively confusing.
- Some of the specialized terminology needed explaining.
- The ordering of the distinct sections was confusing.
- I hadn't really explained what the application would do.
- A entire division which was technically engaging to me was utterly confusing to everyone else.
- Not all web servers use permissions in the identical way.
And on it went!
After all meeting I updated the README according to what group established difficult, afterward I re-tested it alongside the next person.
In total, I paid out about €150 to have a bunch of group criticise me to my face. Hey, cheaper than therapy, right?
I cognize person is going to say "why not fair ask an LLM to simulate a range of users?" The answer is extremely uncomplicated - I desire to conversation to genuine people. People are brilliant! They can create you laugh, you can see their cat whenever it wanders on to the call, they bring a distinctive viewpoint to the problem, and they're really blessed whenever you provision them a €25 voucher. Some volition gladly do it for liberated and create you happy!
When I was doing specialized penning for GOV.UK, all my beautiful prose was stated a second-eye by another human. They eviscerated all my flowery phrases and turned the document into item additional readable. They were the ones who caught the mistakes that no enchantment chequer could. They were capable to have a appropriate conversation alongside me. More importantly, I could hear the frustration in their sound - that's the item which lets you cognize a error needs to be corrected.
I don't assertion that ActivityBot's README is now ideal - far from it - but it is now demonstrably easier to follow. Developers need to conversation to real people. You don't have to pay them if you can't oversee it - but discover a few group who volition conversation aloud during they try to prosecute your instructions. I justify you that your README volition rotate into much improved for it.
