문서는 위키 말고 /docs에 두라는 2022년 글, 깃허브 위키를 안티패턴으로 지목

이 글에 동의함. 깃허브 위키가 /docs 폴더보다 편했던 적이 한 번도 없고, /docs를 GitHub Pages로 바꾸는 건 거의 공짜인데 결과물이 훨씬 낫더라.

그건 깃허브 '위키'가 애초에 위키가 아니었던 게 원죄임. Sourcehut의 'read-only 위키'는 브라우저 편집도 안 되는데 위키라 부르는 식으로 단어가 망가졌어.

내게는 위키 편집이 코드 리뷰를 건너뛴다는 게 최대 이유임. 문서가 조용히 썩는데 /docs PR은 코드 옆 diff로 보이니까.

요즘은 에이전트 덕에 문서를 자주 업데이트하고 검사할 수 있음. 위키도 로컬로 클론해서 AGENTS.md에 경로를 적을 수는 있지만 결국 별도 저장소를 관리해야 해서 귀찮더라.

잠깐, 리뷰 마찰을 추가하는 게 어떻게 rot을 줄이는 거지? 연결이 잘 안 되는데.

Fossil은 이걸 깔끔하게 해결함. 문서를 파일로 두든 위키 네임스페이스로 두든 둘 다 버전 관리되고 클론에 전부 들어있고 렌더링도 똑같아. SQLite가 쓰는 SCM이야.

Fossil이 /docs 디렉터리보다 뭐가 더 낫다는 거지? 그냥 폴더 두면 끝인데.

나는 위키를 문서 용도가 아니라 아이디어 공개 스크래치패드로 쓰는 중임. 아직 이슈로 올릴 만큼 정리 안 된 실험 아이디어를 올려두기 좋더라.

dev 환경 문서는 원 작성자가 아니라 두 번째로 세팅한 사람이 훨씬 고침. 이런 건 코드 리뷰를 강제하면 아예 수정이 안 들어오니까, 빠르고 쉽게 고치게 두는 쪽이 값졌어.

docs 폴더만 건드리는 변경은 리뷰 없이 머지되도록 자동화나 설정으로 빼면 그만임. 웹에서 라이브 편집도 되고.

예전엔 github robots.txt가 /wiki를 막았던 게 최대 이유인 줄 알았는데 지금은 안 보이더라. 공개 편집 가능한 위키만 색인에서 빠진다고 함.

위키도 어차피 별도 git 저장소라 버전 관리가 됨. GitHub도 GitLab도 Forgejo도 마찬가지고, 주장이 결국 '커밋이 소스 저장소와 같지 않다'는 얘기잖아.

그건 태그나 서브모듈로 보완할 수 있고, 저장소가 둘 이상인 프로젝트에서는 원래 그런 문제임.

위키가 이슈보다 진입 장벽이 낮다는 건 사실임. GitHub가 위키 API와 문서만 보강해도 달라질 텐데, 지금은 두면 시간 지나서 다 낡은 정보가 되더라.

위키에 디렉터리가 없는 게 진짜 아쉬움. 메이저 버전별로 문서를 병행 유지보수하려면 구조가 필요한데.

솔직히 마크다운이 GitHub에서 이미 예쁘게 렌더링되는데 왜 docs를 굳이 빌드해서 따로 발행하는지 모르겠음.