The GitHub wiki is an anti-pattern

以下正文同步自 Hacker News，版权归原站所有，已转换为易读排版。

The “should I use the wiki or a docs folder on GitHub?” discussion comes up every 6 months or so, and following Shawn Wang’s three strikes rule I thought it was about time I wrote something down about it.

The initial version of this post opened with “You can use the wiki or a docs folder for your GitHub project, both are valid choices” but as I wrote more, I realised that there is a single reason to use a wiki, and many more reasons not to use the wiki. So many in fact, that I consider using the wiki on GitHub is an anti-pattern.

Let’s start with the benefits of using a wiki:

Really, the only benefit that I’ve been able to find to using the wiki is that it’s always there.

How about the reasons not to use the wiki?

Now that you’re sold on the idea of keeping docs alongside your code, how do you make it easy for people to view them?

Using the /docs folder is the highest effort-to-reward ratio option whilst you’re building out a new product. At some point your docs will outgrow a single folder, and then all bets are off. You’ll want a separate repo with its own build process, pull request review guidelines and a whole host of other things. At that point people are already used to working with docs in a repository, and the migration from /docs to its own repo should be seamless for your contributors.

Whether you agree or disagree, I’d love to hear your thoughts on Twitter

正文由 FLUX 从来源站点 RSS 同步，内容未经改写；遇到排版缺失或需要图片、视频时请以原文为准。