The empathy part I don’t understand. I don’t even need to write good docs for other people. I can do it for myself in 6 months. Anyone who has looked back at their old code should understand that unless you’re doing something entirely trivial a comment or two will be really useful.
This is what you need when writing documentation covering...
1. Where should someone new to the codebase start? Literally, which line in which file?
2. How does the code "fit together"? What is the call-graph of its top use-cases?
3. What are its compile-time and run-time dependencies? Which exact versions of those dependencies were used during development?
4. When something isn't working, how can someone replicate your development environment EXACTLY in order to determine what's different about theirs?
5. How would you approach debugging on this codebase? A detailed write-up or even a video of every step you took could help someone new gain a deep understanding quickly.
That's often not enough when your audience is much more clueless than you assume. You would have to repeat examples over and over and throw some more just in case.
