The “should I use the wiki or a docs folder on Git Hub?” discussion resurfaces every few months. Following Shawn Wang’s three strikes rule, the author argues that using the wiki on Git Hub is an anti-pattern. The only benefit of the wiki is its constant availability, but it lacks versioning, local access, peer review, and branding options.

In contrast, a /docs folder integrates documentation with code, supports versioning, enables pull request reviews, and works with tools like Vale and spellcheck. Images must be hosted elsewhere since the wiki doesn’t support uploads. To publish docs, use a /docs folder with Git Hub Pages and a theme like just-the-docs.

Avoid the gh-pages branch to keep docs versioned with code. As projects grow, docs may move to a separate repo, but contributors will already be accustomed to the workflow. The author invites feedback on Twitter.