인프라 뉴스
깃허브 문서화: 위키 대신 /docs 폴더를 사용해야 하는 이유
The GitHub wiki is an anti-pattern (2022)
Hacker News깃허브 위키는 문서화에 적합하지 않은 '안티 패턴'으로 간주되며, 대신 리포지토리 내 `/docs` 폴더를 활용하는 것이 가장 효과적인 방법입니다.
세 줄 요약
- `/docs` 방식은 문서를 코드와 함께 버전 관리하고, 풀 리퀘스트(PR) 및 GitHub Actions를 통해 검토/린팅 자동화가 가능하여 개발 워크플로우에 통합됩니다.
- 위키는 문서가 로컬에서 접근 불가하거나, 코드 변경과 분리되어 있어 일관된 개발 프로세스 유지와 버전 관리에 어려움이 있습니다.
- 초기에는 `/docs` 폴더를 사용해 GitHub Pages로 배포하고, 프로젝트 규모가 커지면 별도의 전용 저장소로 분리하는 것이 이상적입니다.
작성자는 GitHub Wiki를 사용하는 것을 '안티 패턴'으로 간주하며, 문서 관리에 있어 여러 단점을 지적합니다. 주요 문제점으로는 문서가 코드와 함께 버전 관리되지 않는다는 점과, PR(Pull Request) 과정을 통한 완전한 동료 검토(peer review)를 거치지 못한다는 점을 들었습니다. 또한, 위키는 로컬 환경에서 접근이 어렵고 이미지 업로드 등 기능적 제약도 있습니다.
반면, 리포지토리 내 `/docs` 폴더를 사용하는 방식은 문서화가 코드와 함께 버전 관리되며, 편집 내용에 대해 풀 PR 프로세스를 통해 완전한 검토를 받을 수 있다는 장점이 있습니다. 개발자는 GitHub Actions 같은 도구를 사용하여 문서를 린팅할 수 있으며, 기존의 개발 도구들과도 연동하여 작업할 수 있어 워크플로우 통합성이 높습니다.
이러한 `/docs` 폴더 방식을 구현하려면, 문서 파일을 리포지토리 내에 추가하고 GitHub Pages 빌드를 설정해야 합니다. 초기 단계에서는 하나의 폴더를 사용하는 것이 권장되지만, 프로젝트가 커져서 단일 폴더로 감당하기 어려워질 경우, 별도의 전용 저장소(separate repo)로 분리하는 계획을 세우는 것이 이상적입니다.