Great reading
Everyone should have a sense of documentation, for what is more important than knowing what we think, we want etc and to explain it in a way others will get it?
This connects to the usefulness of making a manual of me like this one I made manual-of-alex.html - easy to do it with AI but you can also do it on their site or manually. I’d recommend starting with a pen and paper.
Practical application:
Based on this, here is what a typical README should include:
Introduction, why the user should care, which pain points are addressed by this project.
Sections with links to them.
Tutorial, an introduction to how this works in practice, made to be repeatable and strong.
How-to, once the user is familiar with how this works, they will have questions for certain use cases. Specific naming.
Reference, the facts about this and how it works. Same structure as the codebase. Informative. Probably not in the readme.
Then finally discussions which is where you say how this should be used? give context, how it stands with other things.
Avoid putting stuff where it doesn’t belong. Explanations in the middle of doing or the opposite. These quadrants need to be split.