GitHub 위키는 안티패턴이다
원제 The GitHub wiki is an anti-pattern (2022)
135 포인트댓글 76

Key Point
프로젝트 초기부터 올바른 문서 관리 방식을 선택하면 버전 관리, 피어 리뷰, 도구 통합 면에서 장점을 누릴 수 있고, 나중의 마이그레이션도 수월해진다.
핵심 요약
- GitHub 프로젝트 문서화 방식으로 위키 vs /docs 폴더 선택 논의가 주기적으로 발생한다.
- 위키의 장점은 리포지토리 어디서나 한 클릭으로 접근 가능하다는 단 하나뿐이다.
- /docs 폴더를 사용하면 문서를 코드와 함께 버전 관리할 수 있어 이전 버전 참조가 쉽다.
- 누군가 리포지토리를 클론해도 /docs는 함께 다운로드되지만 위키는 별도 클론이 필요하다.
- 문서 수정도 코드처럼 풀 리퀘스트를 통해 피어 리뷰를 받을 수 있다.
- GitHub Actions로 Vale 같은 도구를 활용해 문서를 린트하고, VSCode 같은 친숙한 에디터를 쓸 수 있다.
- 위키는 브랜딩 옵션이 제한적이며 모두 비슷한 외관이고, 이미지 업로드 미지원으로 외부 저장소를 써야 한다.
- /docs 폴더에 문서를 두되 GitHub Pages로 빌드·배포하면 보기 좋으면서도 버전 관리 이점을 살릴 수 있다.
- gh-pages 브랜치는 문서 버전 관리를 방해하므로 피해야 한다.
- 초기 단계라면 just-the-docs 테마를 쓰거나 Hugo 같은 도구로 GitHub Action을 통해 배포할 수 있다.
- 위키 페이지 하나만 남겨 실제 호스팅된 문서로 사용자를 유도하면 된다.
- /docs 폴더는 신제품 개발 초기에 노력 대비 이득이 가장 크며, 문서가 커지면 별도 리포지토리로 이전할 수 있다.
- 기여자들이 이미 리포지토리에서 문서 작업에 익숙해 있어 나중에 /docs에서 별도 리포로 이동할 때도 자연스럽다.