Once any document gets over a certain length, a table of contents can be useful. I have a favourite markdown table-of-contents tool but it usually takes me a trip to the search engine to remember what it is! (tl;dr: github-markdown-toc )

This tool generates a neat, nested table of contents based on the titles in the file you give it, and outputs it to standard out. My command looks something like:

gh-md-toc /path/to/project/README.md

Capture the output, put it at the top of your file, and you are all set! For example, a Go SDK project I was working on recently. It's such a small thing but it improves user experience and only takes a moment. When it's time to update, just delete what you have and regenerate a new one!