Hacker News오픈소스 · 도구

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에서 별도 리포로 이동할 때도 자연스럽다.
AI 요약 안내

AI가 한국어로 정리한 내용입니다. 정확한 정보는 원문을 확인해 주세요.

요약 원칙 ↗