The GitHub wiki is an anti-pattern

The debate over whether to utilize the GitHub wiki or a dedicated docs folder for a project has resurfaced periodically, with Shawn Wang’s three strikes rule prompting another perspective on the matter. Initially, the suggestion was that both options are viable, but the writer soon discovered a single compelling reason to employ a wiki, accompanied by numerous drawbacks. This led the author to conclude that employing a wiki on GitHub is fundamentally an anti-pattern.

The perceived advantage of a wiki is its persistent availability. However, if a project commits to keeping documentation in line with its codebase, using the /docs folder emerges as the most efficient approach in terms of effort and reward, particularly during the early stages of product development. As documentation grows beyond a single folder, it becomes necessary to transition to a separate repository equipped with its own build processes, pull request review guidelines, and a suite of other tools.

At this juncture, the project's contributors are already accustomed to working with documentation within a repository, making the migration from the /docs folder to a dedicated repository relatively straightforward for them.

The writer invites feedback on this perspective, whether in agreement or disagreement, and encourages discussion on Twitter.