깃허브 위키는 잘못된 방식입니다
1. 이게 뭔가요?
소프트웨어 프로젝트를 만들 때 설명서나 사용법 같은 문서를 어디에 보관해야 하는지 다루는 글입니다. 깃허브는 개발자가 만든 프로그램 코드와 파일들을 모아두는 곳이고, 깃허브 위키는 여러 사람이 함께 문서를 쉽게 고치고 읽을 수 있게 만든 게시판 형태의 공간입니다. 글쓴이는 프로젝트 안에 따로 문서를 담는 폴더를 만드는 것과 위키를 쓰는 것 중 위키를 사용하는 방식이 잘못된 설계 방식인 안티패턴이라고 주장합니다.
2. 왜 화제인가요?
개발자들 사이에서는 프로그램 설명서를 프로젝트 안의 폴더에 넣을지, 아니면 별도의 위키 기능으로 만들지 주기적으로 논쟁이 이어져 왔습니다. 글쓴이는 처음에는 두 방법 모두 타당하다고 생각했으나, 직접 글을 쓰면서 위키의 장점은 단 한 가지뿐인 반면 단점은 너무나 많다는 점을 깨달았습니다. 저장소 안의 어느 곳에서나 위키 내용에 한 번에 접근할 수 있다는 단 하나의 장점을 제외하면, 버전 관리가 어렵고 다른 사람의 검토를 거치기 힘든 수많은 단점이 존재합니다.
3. 핵심 내용
깃허브에서 설명서를 저장할 때 위키를 쓸 것인가 문서 폴더를 쓸 것인가 하는 논쟁은 약 6개월마다 벌어집니다. 글쓴이는 위키의 장점이 '언제나 그 자리에 고정되어 있다'는 단 하나뿐이라고 말합니다. 반면 문서 폴더를 쓰면 설명서가 소스 코드와 함께 버전별로 관리되어 과거 버전을 쉽게 찾을 수 있고, 다른 사람의 검토와 수정 과정을 거치기 쉬우며, 맞춤법 검사기 같은 익숙한 편집 도구를 쓸 수 있고 그림 파일 넣기도 편리합니다. 따라서 프로젝트 저장소 안에 문서 폴더를 만들어 설명서를 넣고, 무료 웹페이지 호스팅 기능을 설정해 인터넷에 보기 쉽게 출판하는 방법을 추천합니다. 나중에 프로젝트가 커져서 설명서가 방대해지면 그때 독자적인 문서 전용 저장소로 옮기면 됩니다.
4. 나에게 어떤 영향이 있나요?
일반 독자에게는 직접적인 영향이 작지만, 프로그램을 직접 만들고 설명서를 작성하는 개발자들에게는 문서 관리 방식을 바꾸는 실질적인 지침이 됩니다. 앞으로 프로그램을 만들 때 설명서를 위키 대신 코드와 같은 저장소 안의 전용 폴더에 넣어 관리하면, 문서 수정 내역을 코드처럼 철저하게 관리하고 자동으로 예쁘게 꾸며주는 도구의 혜택을 누릴 수 있습니다. 다만 프로젝트가 커져서 문서를 담는 폴더가 너무 비대해지면 그때는 별도의 독립된 저장소로 분리하여 관리하게 됩니다.