The GitHub wiki is an anti-pattern (2022)

summary

GitHub Wikis are an anti-pattern because they separate documentation from the source code, breaking the critical link between versioning and content. Keeping documentation in a /docs folder within the main repository ensures that docs evolve with the code and undergo the same rigorous review process. This approach leverages existing developer tools and automation, making the maintenance of documentation more sustainable and professional. Ultimately, the minor convenience of a wiki's accessibility is far outweighed by the loss of version control and peer review.

key points

1. Documentation stored in a /docs folder is versioned alongside the code, allowing users to easily access the correct documentation for older versions of the software.
2. Using a repository folder enables documentation edits to go through the standard pull request process, ensuring high quality through peer review and automated linting tools.
3. Storing docs in the repo allows contributors to use their preferred local IDEs for editing and keeps the documentation available offline after cloning the project.

who should read it

Software developers and project maintainers who are deciding how to organize their project documentation on GitHub.

discussion positive