I am totally biased towards the README (see Initializer for example).
When you head to some repo, you really expect it to be as self contained as possible. Scattering things around is a deterrent in my opinion. Plus, all the advantages of having it Git’d.
Lastly, it becomes an integral part of the committing process (or at least of the release process) to update the docs.
Although it hasn’t been our standard practice up until now, I do like the idea of making the documentation part of the code base.
However, I don’t know if these is the easiest/best place for implementater-level documentation. Are there any best practices for including documentation in the source when you want to make it easily accessible to non-programmers, and you have more documentation than realistically can “fit” in a single README page?
@mogoodrich I was actually thinking of leveraging gitbook publishing with Markdown in a docs sub-module which would allow to have more pages that are easily navigable - which extends the single readme which now becomes a gateway into the documentation.