What we should do is turn readmes into readmes and not into documentation. Github-like readmes are awful for that purpose. They have no TOC, heading styles are often misleading after two levels, and there is no indenting that could help. For contrast, GTK documentation is great, and so are G docs in general. It usually has toc, intro, description, examples and then detailed and cross-referenced “what you pass and what you get back, and how errors are structured” and formatting to grasp it quickly. Compared to that, usual github docs are just unreadable crap with a little knowledge spread on paragraphs of spoken text.

https://developer.gnome.org/gtk3/stable/GtkWindow.html