I love man pages. But it took me many years before I realized how easy it is to write man pages for tools that I write (and further, I write in markdown and pandoc happily translates them to troff for me).

A few years ago I learned that one can also add a new section to man. I've added the `eg` section, which I fill with examples that I think will be useful to future me. For example, typing `man eg awk` opens up my man page of examples for awk, which is more pointed.