GitHub Wiki는 안티패턴입니다

AI 요약

GitHub 프로젝트 문서를 Wiki에 둘지 저장소의 /docs 폴더에 둘지 묻는 논의는 몇 달에 한 번씩 반복됩니다. 저자는 처음에는 두 방식 모두 유효하다고 쓰려 했지만, 내용을 정리하면서 Wiki를 택할 이유는 하나뿐이고 쓰지 말아야 할 이유는 더 많다고 판단합니다.

Wiki의 장점과 한계

저자가 찾은 유일한 장점은 저장소 어디에서나 한 번의 클릭으로 Wiki 문서에 접근할 수 있다는 점입니다. 두 번째 장점은 없다고 덧붙입니다.

반면 /docs 폴더에 문서를 두면 코드와 함께 버전 관리할 수 있어 이전 코드 버전에 맞는 문서를 찾기 쉽습니다. 저장소를 clone할 때 문서도 함께 내려받습니다. Wiki는 따로 clone해야 하며, 이 기능은 잘 드러나지 않는다고 지적합니다.

문서 수정에도 코드와 같은 절차를 적용할 수 있습니다. Pull Request로 변경 사항을 검토하고, GitHub Actions와 Vale 같은 도구로 문서의 스타일과 문법을 검사합니다. 기여자는 VS Code와 맞춤법 검사기 등 이미 쓰는 도구를 그대로 활용합니다. Wiki는 꾸밀 수 있는 범위가 제한돼 페이지 모양이 대체로 비슷하고, 이미지 업로드를 지원하지 않아 이미지를 다른 곳에 보관해야 한다는 점도 단점으로 듭니다.

/docs 문서를 공개하는 방법

저자는 문서를 저장소의 /docs 폴더에 두고 GitHub Pages로 공개하라고 제안합니다. 문서를 gh-pages 브랜치에만 올리면 코드와 함께 버전 관리할 수 없으므로 피하라고 합니다. 시작 단계라면 Just the Docs 테마를 사용하고 GitHub가 빌드와 배포를 맡도록 구성할 수 있습니다. 직접 빌드 과정을 만들고 싶다면 Hugo 같은 도구와 GitHub Action을 활용합니다. Wiki에는 호스팅한 문서로 안내하는 페이지 하나만 남깁니다.

저자는 /docs가 새 제품의 문서를 키워 가기에는 작업량 대비 효과가 좋은 선택이라고 봅니다. 문서가 폴더 하나로 감당하기 어려울 만큼 커지면 별도 저장소와 자체 빌드 과정, Pull Request 리뷰 지침 등을 마련해야 합니다. 그때도 기여자들이 저장소 안에서 문서를 다루는 방식에 이미 익숙하므로 별도 저장소로 옮기는 과정이 매끄럽다고 설명합니다.

Lobsters 반응

• @realkc — “문서 브랜딩 기회가 제한적이고 페이지가 다 비슷하다”는 점은 문서를 읽는 사람 입장에서 단점이라고 부르기 어렵습니다. 다른 지적에는 동의합니다.
• @mlatu — Fossil을 들어 봤나요? Git과 가져오기·내보내기를 할 수 있는 분산 버전 관리 시스템입니다. Wiki, 이슈 트래커, 포럼, 채팅 기능도 통합돼 있습니다. 특히 Wiki가 프로젝트 폴더를 가리키게 설정하면 코드와 같은 시스템으로 Wiki를 버전 관리할 수 있습니다.
  • @hjvt — 문서를 코드와 함께 버전 관리하는 건 정말 중요합니다. 프로젝트의 GitHub Wiki를 살펴보면 내용 일부가 심하게 오래된 경우가 꽤 많습니다.
• @legoktm — “문서 수정도 코드처럼 Pull Request로 충분히 검토한다”는 점이 가장 큰 차이이자 Wiki의 주요 장점입니다. Wiki는 누구나 바로 수정할 수 있고 사전 검토를 요구하지 않습니다. 프로젝트나 커뮤니티에 따라 다르겠지만, 이를 통해 기여자가 문서를 직접 보완하도록 돕는 방식을 좋아하는 사람도 있습니다. 반대로 신중한 검토와 편집을 위해 사전 승인을 요구하는 것도 타당합니다.

원문: Michael Heap / 번역·요약: Trawling