Why use GitHub Wikis?

March 19, 2015 • Tagged: git

I usually disable GitHub’s wikis on my repositories. I think they are occasionally useful, but I much prefer maintaining documentation as Markdown files in a folder inside the repository itself. This is why…

Keeping documentation in the repository allows the docs to be updated and maintained alongside the codebase they’re documenting. The docs remain in sync with the code across branches and throughout the rest of the standard git workflow.
This also means you have a nice history of your documentation which, again, is tied to the history of the codebase.
It’s possible for documentation changes in the repo to be submitted, reviewed, and merged or rejected as pull requests. This isn’t true of wikis.
The index for a GitHub wiki is difficult to find and feels like a third-class citizen. A list of files in a folder is easy to find, and it’s highly usable. (Use t to filter by name!)
GitHub renders Markdown files nicely in its web browsing interface. And you can add a README.md to your Docs folder as a sort of “wiki home page”. It’ll be displayed when someone views that folder in the GitHub web interface.
As far as I can tell, wikis don’t integrate with GitHub’s notification system. It’s difficult to monitor changes.
Relative links to other files in the repo are easy to add to GitHub Markdown files.
Finally, GitHub’s web editing interface works perfectly well for updating Markdown files in the repo on the fly. GitHub even makes it easy to fork the project and submit a PR in a couple clicks.

For inspiration, look at ReactiveCocoa’s Documentation folder. It has a home page and index as you’d expect, it remains in sync with the code, changes can be made and reviewed with the normal branch/PR model, relative links between files exist like you’d expect, and editing the files online is easy.