GitHub Wiki is an Anti-Pattern for Documentation, Recommends /docs Folder

Critique of GitHub Wiki

The GitHub wiki is identified as an anti-pattern for project documentation. Its primary benefit is accessibility via a single click from the repository. However, this single advantage is outweighed by numerous drawbacks that hinder effective documentation management.

Limitations of Wiki Documentation

Key limitations of using the GitHub wiki include the lack of versioning alongside code, making it difficult to access documentation for older code versions. Documentation stored in a wiki is not available locally when a repository is cloned, requiring a separate wiki clone. Additionally, wiki edits do not undergo the same peer review process as code changes via pull requests, and wikis offer limited branding opportunities and do not support image uploads directly.

Advantages of In-Repository Documentation

Storing documentation in a `/docs` folder within the main repository provides several benefits. Documentation is versioned with the code, ensuring consistency. It is accessible locally upon cloning the repository, and edits can be subjected to full peer review through the pull request process. This approach also allows for linting with tools like Vale and enables developers to use familiar tooling such as VSCode with spellcheck.

Recommended Implementation

To implement in-repository documentation, it is recommended to add documentation to a `/docs` folder, avoiding the `gh-pages` branch to maintain versioning with the code. Setting up a GitHub Pages build can publish these documents. For new projects, using the `just-the-docs` theme with GitHub's build process is suggested. Alternatively, custom workflows with tools like Hugo can be used with a GitHub Action for publishing. A single wiki page can then direct users to the hosted documentation.