Github Readme vs Wikis
Github Recommendations:
A README file quickly tells what your project can do, while you can use a wiki to provide additional documentation. Reference
Editor Features Comparision
- README.md (No editor tools)
2. Wikis (Editor tools exist)
Conclusion: Wikis WON
Footer, Sidebar & Search Comparison
- README.md (No feature exists)
- Wikis (Default Sidebar along with Search feature, custom footer and sidebar available)
Conclusion: Wikis WON
VCS Comparison
- README.md has branches, history management, commit message with author name, etc
- Wikis also has all the above-mentioned things, but a PR (Pull Request) can’t be created for a branch, it should be directly merged to master via Github CLI.
Conclusion: README.md WON
Multiple Pages Comparison
- README.md: New pages can be created but we need to mention the list for the new pages (along with a link) every time in the required README.md
2. Wikis: New pages can be easily created and listed by creating a file in the Wiki Repo or just by clicking on “New Page”
Conclusion: Wikis WON
File Extension Comparison
- README.md uses .md extension
- Wikis also use .md extension
Conclusion: No one WON or Both Won
Repo Comparison
- Same project repo is used for maintaining README.md
- Different repo is used for maintaining Wikis
Conclusion: Wikis WON
Personal Opinion:
I would go for Github recommendation which prefers for longer documents, we should use Wikis.
All others are positives, the most important one is that you can quickly create pages (along with a list), and format easily your document whereas this will be a little time taking in the README.md case
The negative one is that PR can’t be created, so if there are multiple contributors to WIKIS, it will be difficult to review and comment for a change.
If you have a team that has to maintain a longer document, What’s your opinion? What to use? Wikis or README.md?
Wait Wait! Have you watched my recent video on the Importance of Unit Testing? Watch the below link and subscribe to my channel.