📖Docs vs Wiki Debate Resurfaces Every 6 Months
Why the docs folder wins over wiki every time
TL;DR
The age-old debate between using a wiki or a /docs folder for project documentation reemerges every six months. The /docs folder offers version control and peer review, making it the superior choice for most projects.
The debate over whether to use a wiki or a /docs folder for project documentation has resurfaced once again. The key argument in favor of the /docs folder is that it integrates seamlessly with version control systems, allowing for full peer review and versioning of documentation alongside code. This means that documentation edits receive the same scrutiny as code changes, ensuring quality and consistency. Wikis, on the other hand, offer limited branding opportunities and no version control, making them less suitable for projects that value transparency and collaboration. The /docs folder also supports GitHub Actions for linting documentation and can be easily set up with GitHub Pages for publishing. As projects grow, a separate documentation repository might be necessary, but contributors familiar with working in a repository will find the transition smooth.
Key Points
The /docs folder supports GitHub Actions for linting documentation using tools like Vale.
Documentation in /docs can be easily published via GitHub Pages with the just-the-docs theme.
Wikis lack support for image uploads and offer limited branding opportunities.
Contributors familiar with repository workflows will find the transition to a separate doc repo seamless.
A single wiki page can direct users to hosted documentation, but lacks the benefits of /docs.
Why It Matters
If you're maintaining a project's documentation, using a /docs folder ensures version control and peer review, enhancing quality and consistency. While wikis are always available, they lack the integration and support for tooling that /docs offers. As projects grow, the transition to a separate documentation repository is smoother for contributors used to working in a repository.
Comments
Be the first to comment
Enjoyed this article?
Get it daily. 7am. Free. Reads in 5 minutes.
Join 3,488 builders reading daily.