GitHub wikis are often criticized as an anti-pattern, but the useful question is narrower: when does a separate wiki make documentation easier to maintain, and when does it create avoidable operational friction? Michael Heap’s post, “The GitHub wiki is an anti-pattern,” argues from a software-maintenance perspective that documentation generally belongs with the code it describes. That is a strong default, not a universal rule.
The central distinction is provenance. A wiki is a separate Git repository with its own history, permissions, review conventions, and publishing path. A `docs` directory in the application repository can place a documentation change beside the code change that makes it necessary. That does not automatically make every documentation edit better, but it makes the relationship between behavior and documentation easier to inspect during pull requests, code review, and later debugging.
The main counterargument is friction. A browser-editable wiki lowers the cost of a small correction, especially for someone who is not already working in the repository. That matters because documentation quality depends on whether people will make incremental updates. Requiring a clone, branch, pull request, approval, or CI run for every typo can discourage useful edits. The practical lesson is not that all documentation must pass through the code-review pipeline; it is that teams should deliberately choose which documentation changes need review and which can be handled through a lighter path.
The strongest reason to prefer `docs` is therefore not ideological purity. It is that versioned documentation can be tested, built, searched, and changed using the same tooling as the rest of the project. A repository can also expose documentation through GitHub Pages or another static-site build without moving the source into a wiki. The supplied material does not establish a specific build setup, but it does support the general comparison: a wiki is separate from the application repository, while an in-tree documentation directory can participate directly in repository workflows.
Scale introduces a different question. Heap’s post says that documentation may eventually outgrow a single folder and require a separate repository with its own build process. The supplied evidence does not identify a precise threshold, and there is no reason to treat that transition as inevitable. Large documentation sets may need separate ownership, navigation, localization, or publishing infrastructure, but those needs can sometimes be met with a dedicated documentation repository, a documentation site, or a more structured monorepo. The important point is to separate the reason for a move from the mere existence of many files.
Security and governance also differ. A wiki’s permissions and edit history are managed through GitHub’s wiki and repository controls, while in-tree documentation inherits the repository’s contribution and review rules. Neither model is inherently secure or insecure. The operational risk is choosing a workflow by convenience alone, then discovering that documentation changes are invisible to reviewers, hard to reproduce, or maintained by a different group than the code. Teams should make those responsibilities explicit.
The best default for most product and engineering documentation is a versioned `docs` tree with a lightweight process for small corrections. A wiki can still be reasonable for notes that are intentionally separate from release engineering, for documentation maintained by a different team, or for quick collaborative capture where formal review would be counterproductive. The decision should follow the documentation’s lifecycle: who owns it, how it changes, how it is reviewed, and how readers find the version that matches the software they use.