소프트웨어 프로젝트에서 소스코드만큼 중요한 것이 개발문서다. 굳이 포스트를 할애하면서까지 개발문서의 중요성을 언급하지 않아도 개발문서의 중요성은 모두들 공감할 것이다. 특히 프로젝트의 규모가 클 수록, 프로젝트의 복잡도가 높을 수록, 프로젝트에 참여하는 멤버가 많을 수록 개발문서의 중요성은 커진다. 잘 작성된 개발문서는 커뮤니케이션 비용을 줄여주고, 버그를 생성할 가능성을 낮춰준다.
하지만 개발문서의 가장 큰 단점이 있었으니 바로 귀차니즘이다. 개발문서를 작성하는 일은 귀찮다. 개발자는 본능적으로 문서작성보다는 코딩을 좋아한다. 따라서 개략적인 설계안이 나오면 바로 코딩에 들어간다. 열심히 집중해서 코딩을 끝 마치고나면 개발문서 작성은 숙제로 남아있게 된다. 방학동안 신나게 놀고, 개학이 다가오면 남아있는 숙제들처럼 말이다.
그래도 개발문서는 써야한다. 귀차니즘을 최소화하기 위해서는 찾아보기 쉽고, 작성하기 쉽고, 수정하기 쉽게 개발문서를 만들어야한다. 그래서 사용하는게 위키(Wiki)인데, 깃허브는 저장소마다 위키 기능을 제공한다. 소스코드가 위치한 곳에 개발문서를 작성할 수 있기 때문에 귀차니즘의 정도를 약간이라도 줄여준다.
위키의 활성/비활성화
깃허브에 저장소를 생성하면 기본적으로 위키 페이지가 자동으로 생성된다.
깃허브 저장소 페이지에서 'Wiki' 탭을 누르면 깃허브의 위키 기능을 사용할 수 있다. 만약 'Wiki' 탭이 보이지 않는 경우라면 저장소에서 위키 기능이 비활성화되어 있는 상태다.
위키 기능을 활성화하거나 비활성화하려면 'Settings' 탭으로가서 Features 항목에서 Wikis 체크박스를 선택하면 저장소에서 위키를 활성화 또는 비활성화 할 수 있다.
깃허브 위키 페이지
깃허브 저장소의 'Wiki' 탭으로 들어가면 위키 페이지를 볼 수 있다. 만약 작성된 위키 페이지가 없다면 새로운 페이지를 작성할 수 있다. 생성된 위키 페이지가 없다면 화면 중앙에 나오는 'Create the first page' 버튼을 눌러서 첫 위키 페이지를 작성할 수 있다. 이미 위키페이지가 있는 경우 오른쪽 상단에 'Edit' 버튼을 눌러서 현재 보고 있는 위키 페이지를 수정하거나 'New' 버튼으로 새로운 위키 페이지를 생성할 수도 있다.
깃허브 위키 페이지는 '마크다운(MarkDown)' 문법으로 작성할 수 있다. 깃허브 웹 페이지에서 문서 생성이나 수정을 하면 위 그림같은 에디터가 뜬다. 이 에디터에서 마크다운으로 문서를 작성하거나 수정할 수 있다. 마크다운 문법이 익숙하지 않은 사용자를 위해서 깃허브는 몇가지 도움버튼(?) 같은 것들을 제공하고 있는데 조금 사용하다보면 마크다운이 손에 익어서 키보드만으로 수정할 수 있게 될 것이다.
위키 에디터의 가장 하단에는 'Edit message' 섹션이 있다. 이 부분에는 소스코드의 커밋로그처럼 위키 문서를 왜 수정했는지 간략한 요약을 적어둘 수 있다.
사실 저장소의 위키도 별도의 git 저장소로 관리된다. 위키 페이지의 오른쪽 하단을 보면 저장소의 위키를 수정할 수 있는 또 다른 저장소 주소를 확인할 수 있다. 대부분 repository.wiki.git 처럼 중간에 'wiki'가 들어간 주소되어 있다. 이 주소를 이용해서 로컬에 위키를 clone해서 VSCode 같은 에디터로 편집할 수도 있다.
사이드바와 바닥글
깃허브 위키에 문서를 추가하다보면 '메뉴' 혹은 '카테고리' 같은 구성으로 위키 페이지를 구성하고 싶은 경우가 있다. 마치 블로그에서 글을 읽다가 메뉴나 카테고리를 클릭하면서 문서를 찾아갈 수 있는 것처럼 깃허브 위키 페이지도 구성하고 싶을 수 있다.
기본적으로 위키 페이지의 오른쪽 'pages' 부분에는 위키 문서들이 제목의 알파벳 순으로 정렬되어 보여진다.
개발문서는 대부분 제목의 알파벳 순서가 아닌 비슷한 주제끼리 묶어서 보는 경우가 많다. 깃허브 위키에는 '사이드바(Sidebar)' 기능이 있어서 이 기능을 이용하면 문서들을 카테고리화할 수 있다.
Pages 항목 아래쪽을 보면 '+ Add a custom sidebar' 버튼이 있다. 이 버튼을 누르면 사이드바를 편집할 수 있는 에디터 창이 나온다.
에디터 창을 보면 알수 있겠지만 사이드바는 이름이 '_Sidebar'인 문서일 뿐이다. 이 분서를 깃허브 위키 페이지에서 사이드바 부분에 렌더링해서 보여주는 것 뿐이다.
보여줄 사이드바 문서가 있으면 깃허브 위키 페이지는 Pages 대신 사이드바를 표시한다. 사이드바 옆에는 연필 아이콘이 있어서 언제든지 편집할 수 있다. 비슷한 방법으로 '+ Add a custom footer' 버튼을 눌러서 위키에 바닥글을 추가할 수도 있다.
흥미로운 점은 사이드바와 바닥글을 위키를 디렉토리별로 구분해서 관리할 수 있다는 점이다. 위키 저장소를 로컬에 clone하고 주제별로 디렉토리를 생성한 다음 디렉토리별로 '_Sidebar.md' 파일과 '_Footer.md' 파일을 만들어두면, 위키 문서를 웹에서 볼 때 그 문서가 위치한 디렉토리에 있는 사이드바와 바닥글이 렌더링되어 보여진다. 주제별로 사이드바를 다르게 관리하고 싶은 경우 유용하다.
이미지 추가
깃허브 이슈에서처럼 위키 페이지에 이미지를 추가하면 좀 더 이해하기 쉬운 문서를 작성할 수 있다. 하지만 위키 에디터는 깃허브 이슈에서처럼 이미지를 드래그&드롭해서 쉽게 업로드하는 기능을 제공하지 않는다.
위키에서 이미지를 사용하는 가장 쉬운 방법은 이슈 혹은 이슈의 커멘트 에디터에 이미지를 드래그앤드랍하는 것이다. 그러면 위 그림에서 볼 수 있는 것처럼 깃허브 서버로 이미지가 업로드되고, 업로드된 이미지가 마크다운으로 표시된다. 이 마크다운을 그대로 위키 페이지에 붙여 넣으면 이미지를 사용할 수 있다.
다만 이렇게 업로드된 이미지는 사용자가 관리할 수 없다. 즉, 잘 못올라간 파일이 있더라도 서버에서 딱히 지울 방법이 없다. (이렇게 올린 파일이 언제 지워지는지도 잘 모르겠다.)
정석적인 방법은 위키 저장소를 clone 받아서 imgage 디렉토리를 만들고, 그 곳에 업로드해서 위키 문서와 함께 사용하는 것이다.
위키 히스토리
위에서 위키 문서도 깃 저장소로 관리가 된다고 했다. 따라서 위키 문서의 수정 히스토리도 조회해볼 수 있다.
위키 페이지의 상단을 보면 페이지가 몇 번 수정되었는지 확인할 수 있고, '1 revision' 부분을 클릭하면 수정 히스토리도 조회할 수 있다. 특정 부분과 현재 페이지가 어떤 부분이 다른지 diff 도 조회할 수 있다.
위키 문서 검색
깃허브는 위키 문서에 대한 검색 기능도 제공한다. 깃허브 전체 범위에서 검색을 할 수도 있고, 특정 저장소나 Organization 범위에서 검색을 할 수도 있다.
위키 검색을 할 때 문서의 검색 범위를 지정하기 위해서는 다음을 추가하면 된다.
| Qualifier | 의미 |
| user:USERNAME | USERNAME 이 소유한 저장소에서 조회 |
| org:ORGNAME | ORGNAME organization에서 문서 조회 |
| repo:USERNAME/REPOSITORY | USERNAME/REPOSITORY 저장소에서 문서 조회 |
| in:title | 조회 키워드가 제목에서 매칭되는 문서 조회 |
| in:body | 조회 키워드가 본문에서 매칭되는 문서 조회 |
| updated:>2020-11-01 | 2020년 11월 1일 이후에 업데이트된 문서를 대상으로 조회 |
in:title 혹은 in:body 퀄리파이어가 검색 쿼리에 포함되지 않으면 둘 다를 대상으로 한다.
댓글