GitHub 위키는 안티패턴이다 (2022)

GitHub 프로젝트 문서는 위키보다 /docs 폴더에 코드와 함께 관리하고 GitHub Pages로 게시하는 방식을 권장함 문서를 코드와 함께 버전 관리하면 이전 버전의 문서를 쉽게 찾을 수 있고, 저장소를 복제할 때 문서도 함께 내려받을 수 있음 문서 변경에도 풀 리퀘스트를 통한 동료 검토를 적용하고, GitHub Actions 기반 린트와 익숙한 편집 도구를 활용할 수 있음 위키의 장점은 저장소 어디서든 한 번의 클릭으로 접근할 수 있다는 점이지만, 브랜딩이 제한적이고 이미지 업로드를 지원하지 않음 새 제품을 만드는 동안에는 /docs가 노력 대비 효과가 높은 선택이며, 문서 규모가 커지면 별도 저장소와 전용 빌드 절차로 옮길 수 있음 위키보다 코드와 함께 문서를 관리해야 하는 이유 GitHub 위키와 문서 폴더 중 무엇을 쓸지에 대한 논의는 약 6개월마다 반복되며, Shawn Wang의 세 번의 법칙(three strikes rule)에 따라 이번에 정리하게 됨 위키와 문서 폴더 모두 유효한 선택이라는 초기 판단과 달리, 위키의 유일한 장점은 저장소 어디서든 한 번의 클릭으로 접근 가능하다는 점이며 사용하지 않을 이유가 훨씬 많음 /docs 폴더는 문서를 코드와 함께 버전 관리하므로 과거 코드 버전에 맞는 문서를 쉽게 찾을 수 있음 위키 문서는 일반 저장소를 복제할 때 로컬로 내려받아지지 않음 위키를 별도로 복제할 수는 있지만, 잘 드러나지 않는 기능임 문서를 코드처럼 다루면 풀 리퀘스트를 통한 동료 검토와 기존 개발 도구를 활용할 수 있음 GitHub Actions에서 Vale 같은 도구로 문서를 린트할 수 있음 맞춤법 검사 기능을 갖춘 vscode처럼 이미 익숙한 도구로 작업할 수 있음 위키는 브랜딩 선택지가 제한되어 대부분 비슷하게 보이며, 이미지 업로드를 지원하지 않아 이미지를 다른 곳에 저장해야 함 /docs와 GitHub Pages로 게시하고 확장하기 문서는 저장소의 /docs 폴더에 두고, GitHub Pages 빌드를 설정해 게시함 문서 원본을 gh-pages 브랜치에서 관리하면 코드와 함께 버전 관리할 수 없으므로 피해야 함 처음 시작한다면 just-the-docs 테마를 사용하고 GitHub에 빌드와 게시를 맡기는 방식을 권장함 Hugo 등으로 자체 워크플로를 구성한다면 문서 게시용 GitHub Action을 활용할 수 있음 위키에는 게시된 문서로 안내하는 페이지 하나만 남김 새 제품을...