GitHub wiki 是一种反模式

概述

作者认为「该用 wiki 还是仓库里的 docs 目录」这个每隔半年就会被翻出来的问题，答案其实很清楚：用 wiki 只有一个好处，不用它的理由却有一大堆。唯一的好处是它总能从仓库任意位置一键到达；而代价包括文档无法与代码一起版本化、克隆仓库时拿不到文档、编辑无法走 pull request 评审、无法用 GitHub Actions 配合 Vale 之类的工具做检查，也不能用自己熟悉的编辑器并享受拼写检查。他的建议是把文档放进仓库的 /docs 目录、用 GitHub Pages 发布，再留一个 wiki 页面把访客导向托管好的文档。