So, call to action: if you are writing any kind of documentation, before explaining how to fix the problem, teach the user how to diagnose it.
Source: Why Linux Troubleshooting Advice Sucks
I’ve been writing documentation for myself for years, and been using Linux for 20 years and I still struggle with the basics cos most documentation for Linux fucken sucks.
- Teach the user how to diagnose the issue so they can confirm the solution you have is indeed for their issue.
- Explain why this is happening.
- Provide the solution. Could be a bash one-liner they can copy-paste. Could be a script (explain how to run it). Could be a patch (explain how to apply it). Don’t just say “this is an exercise left to the reader.”
And no, “reading the source” doesn’t help. Neither does “read the man pages”; the only man page worth anything is the one for nmap.
If you’re one of those people that say that you can go fuck yourself, hard, in the ass, no lube.