"깃허브 위키 쓰지 마세요" 안티패턴이라 불리는 이유

요약 깃허브 저장소를 운영할 때 문서를 어디에 둘 것인가는 개발자들 사이에서 몇 달 주기로 반복되는 오랜 논쟁거리입니다. 저장소 기본 탭에 있는 ‘위키(Wiki)’를 쓸 것인지, 아니면 코드와 함께 ‘/docs’ 폴더를 둘 것인지에 대해 필자는 위키를 사용하는 것이 사실상 ‘안티 패턴(Anti-pattern)’에 가깝다고 단언합니다. 필자가 꼽은 깃허브 위키의 장점은 단 하나뿐입니다. 저장소 어디서든 클릭 한 번으로 바로 접근할 수 있다는 점 외에는 내세울 만한 강점이 전혀 없다는 것입니다. 반면 코드와 함께 ‘/docs’ 폴더를 관리해야 하는 이유는 명확합니다. 가장 큰 장점은 코드와 문서가 동일하게 버전 관리(Version Control)된다는 점입니다. 구버전 코드가 필요할 때 당시 문서도 즉시 함께 확인할 수 있으며, 저장소를 로컬로 클론할 때도 문서가 빠짐없이 함께 받아집니다. 위키는 별도 클론이 가능하긴 하지만 숨겨진 기능에 가깝습니다. 또한 문서 수정 역시 일반 코드처럼 풀 리퀘스트(PR) 프로세스를 거치며 동료 검토(Peer Review)를 받을 수 있습니다. Vale 같은 도구를 깃허브 액션(GitHub Actions)과 연동해 문서 린트 및 맞춤법 검사를 자동화할 수 있고, 기여자들은 VS Code 등 손에 익은 개발 툴을 그대로 쓸 수 있습니다. 반면 위키는 이미지 직접 업로드를 지원하지 않아 별도 호스팅이 필요하고, 디자인 커스텀이 제한되어 브랜드 개성을 살리기 어렵습니다. 이에 따라 필자는 ‘/docs’ 폴더에 문서를 두고 깃허브 페이지(GitHub Pages)나 Hugo 빌드 워크플로를 연동해 배포하는 방식을 권장합니다. 처음 시작할 때는 Just-the-docs 테마를 활용하고, 기존 위키에는 배포된 공식 문서 링크만 안내하는 단일 페이지를 남겨두는 방식이 효율적입니다. 프로젝트가 커져 독립된 문서 전용 저장소로 분리하더라도, 이미 레포지토리 기반 협업에 익숙해진 기여자들은 큰 혼선 없이 자연스럽게 적응할 수 있기 때문입니다.