From Michaelheap · · 50s
GitHub wiki is an anti-pattern
GitHub wiki usage is an anti-pattern for documentation.
In brief
GitHub wiki usage is an anti-pattern for documentation. Using GitHub wiki for documentation is an anti-pattern due to versioning issues and limited tooling support. Originally reported by Michaelheap.
The wiki debate
The should i use the wiki or a docs folder on github discussion comes up every 6 months.
Wiki benefits
You can get to wiki contents in a single click from anywhere in the repo.
Wiki drawbacks
Documentation is versioned alongside code when using the docs folder.
Wiki limitations
Documentation edits get full peer review through pull request process.
Better alternatives
Add docs to repository in the docs folder and set up github pages build.
Migration strategy
When docs outgrow a single folder, migrate to a separate repo with its own build process.
The short version
Using GitHub wiki for documentation is an anti-pattern due to versioning issues and limited tooling support.
