>>"my code speaks for itself, no need for comments"
I think most code needs some comments, but clear and self-contained code, shouldn't need line-by-line commentary stating the obvious. I can sight-read code, I can't understand intent..
Vast documents separate from the code tend not to be read, people tend to be focused on the problem at hand, and want to go straight to that. Document structures, and expectations with those. Keep stuff localized and compartmentalized as much as possible.
People doing care taking work tend to be there to put out fires, and fix real specific problems. There are a lot of people complaining and looking for a quick fix, so focus on what they might need to know in a hurry, follow that with more detail.
Code should be readable. Clean and consistent style and indenting. People can have strong views on how that should look like, but there are tools to actually reformat to whatever they want, and also the act of reformatting manually to one's own style can force neural path ways to be traversed.
Where code sections spans multiple screen pages, commentary on what a brace closes can help when skimming later.
Avoid uses of globals and dumb variable / function labeling.
Generally a good explanation of the goals and function of the following code.
Commentary on any quirky behaviour or expectations, or the software or hardware.
If I've had to debug something, and code was changed, and explanation and date are helpful to line up with other correspondence or reports.
I put in thoughts about what will and will not be seen at a given point, and things I know it won't handle without more thought. And the pitfalls I see.
I also add in comments about who asked for a particular function, settings, or code change, and I perhaps leave an audit trail of those as the settings change/evolve based, especially when I expect a circular conversation about how something should work, and about how the HW/SW actually behave vs the person who might not.
Above all have some narrative, even if it's with your future self. Solid code has a surprisingly long shelf-life.
IDE's have become better over the years, but lack consistency, I like having good static analysis tools when trying to understand others code, especially if it spans hundreds of directories, and thousands of files and functions. A least some of them can chart relationships really well, some of these might be good for generating a good top level overview. Good cross-referencing can help to see how many places use a function, and where those are. It helps understand the magnitude of the danger from changing something that looks otherwise innocuous.
