Fully agree -- documentation as markdown committed alongside the code (and processes to ensure that it is kept up-to-date, discoverable and browsable) is the best way to avoid docs going stale or abandonned.
You can go all the way and make a Hugo website out of those Markdown docs pretty easily too. If anyone wants help doing this, feel free to drop me a line!