My approach is to keep them minimal. Make them a table of contents and spark notes, spread them across the repo, keep them up to date as the repo changes.

Something is better than nothing. It's pretty hard to have bad ones, also takes effort to craft good ones. The bad ones are the ones with incorrect information.