Comment by crayola

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.