Michael Heap makes the case for keeping GitHub docs with code
The author argues that a project’s /docs folder is easier to maintain than a GitHub wiki, with a separate repository an option as documentation grows.
Michael Heap argues that GitHub project maintainers should avoid using wikis for documentation, calling them an “anti-pattern” in a blog post published on 23 September.
Heap says the wiki’s main advantage is that it is readily available. He argues that keeping documentation in a /docs folder alongside the code makes it easier for users and maintainers to keep the two in sync.
For new products, Heap recommends /docs as a straightforward option, with the documentation published through GitHub Pages. The post frames the choice as a recurring discussion among project maintainers.
As documentation grows beyond a single folder, Heap suggests moving it to a separate repository, with its own build process and guidance for reviewing contributions.
The post presents Heap’s view; the supplied material does not include an independent comparison of the approaches or establish that wikis are unsuitable for every project.
