The GitHub wiki is an anti-pattern (2022)

Your documentation's versioning and review process now aligns directly with your code's.

Developer Michael Heap argues that the GitHub wiki feature is an anti-pattern for project documentation. Heap contends that while the wiki offers the single benefit of being easily accessible from the repository, its drawbacks significantly outweigh this advantage. He highlights that documentation within a /docs folder is versioned alongside the code, easily accessible locally when a repository is cloned, and benefits from the same pull request review process as code. Furthermore, using a /docs folder allows for integration with tools like GitHub Actions for linting and enables contributors to use familiar development environments for editing documentation. Heap suggests using a /docs folder within the repository, publishing it via GitHub Pages, and linking to it from a single wiki page as a superior approach. He recommends tools like the 'just-the-docs' theme for easier setup and notes that this method scales well until documentation requires its own separate repository.

Heap's argument suggests a market shift away from ephemeral, easily accessible documentation towards integrated, version-controlled content. This approach treats documentation as a first-class citizen alongside code, subject to the same rigorous development practices. The implication is that projects prioritizing robust documentation should adopt this integrated strategy, enhancing the quality and reliability of their project knowledge base.

For developers and teams, this means a more streamlined workflow where documentation updates are seamlessly incorporated into the code review cycle. It also implies a potential future where dedicated documentation platforms might become less prevalent for open-source projects, with standard repository structures becoming the norm. Teams should consider migrating existing wiki content to a version-controlled folder to leverage these benefits.