The GitHub wiki is an anti-pattern
4 hours ago
- GitHub wiki has only one benefit: one-click access from anywhere in the repository.
- Using a /docs folder alongside code provides versioned documentation, local availability when cloning, peer review via pull requests, and integration with tools like GitHub Actions and Vale.
- Wiki lacks features like image uploads and branding options, and documentation edits do not receive the same review process as code.
- Recommended approach: store docs in the /docs folder, set up GitHub Pages (e.g., using just-the-docs theme), and add a single wiki page directing users to hosted docs.
- The /docs folder offers high effort-to-reward ratio for new projects; later migration to a separate repo should be seamless for contributors.