GitBook을 사용해 보자

GitBook이란?

GitBook은 협업을 위한 문서 작성 플랫폼입니다. 업무 가이드라인, API 명세서 작성 등의 기본 템플릿을 제공합니다. Git 형식의 협업 및 버전 관리를 지원합니다.

GitBook 시작하기

우선 GitBook에 접속한 뒤, 계정이 있다면 Sign in, 없다면 Start for free 혹은 Sign up with GitHub를 선택해 줍니다. 계정이 없다면 구글이나 GitHub 계정 중 원하는 계정을 연동하시면 됩니다.

Organization 이름과 사용 목적은 원하는 대로 설정합니다. 이름은 나중에 바꿀 수도 있습니다.

협업 도구이므로 팀원 초대가 가능합니다. 함께 문서를 관리할 팀원이 있다면 초대해 주세요.

기존에 사용하던 문서가 있다면 GitBook 지원 문서로 변환할 수 있습니다. 기존 작업물을 옮기려면 자료 형태에 맞는 선택지를 골라 주시고, 새로 시작하는 경우라면 넘어가시면 됩니다.

Space 생성

아까 생성한 Organization의 Team Library 내에서 관리하는 문서들의 집합을 Space라고 부릅니다. Space는 Collection이라는 그룹으로 관리할 수도 있습니다. 가입 후 기본적으로 Untitled라는 이름으로 Space가 하나 있을 겁니다.

원하는 제목과 문서로 관리해 봅시다. 페이지의 Use a Template 버튼을 누르면 해당 페이지에 여러 형태의 템플릿 중 하나를 적용할 수 있습니다. 저는 API Docs를 선택하겠습니다.

수정과 저장

GitBook은 작업 내역을 실시간으로 저장합니다. 즉 따로 저장을 할 필요가 없습니다. 구글 문서나 노션을 생각하시면 됩니다.

자동 저장을 해제하고 다시 설정할 수도 있습니다. 그럴 땐 우측 상단의 세 점 버튼을 눌러서 Lock/Unlock Live Edits 버튼을 눌러 전환합니다.

Live Edit이 아니라면 수정 버튼을 누른 후의 변경점을 Merge 버튼을 눌러 저장하게 됩니다. 수정한 점을 기록할 수도 있습니다. 프로그래밍을 하셨다면 익숙하실 Git의 Commit Message입니다. 다만 여러 명이 같은 문서를 작업하게 될 텐데, Git처럼 수정점을 리뷰하는 과정이 필요할 수 있습니다. 그런 경우에는 Change Request를 남길 수 있는데, Live Edit이 비활성화된 상태에서 Submit for review 버튼을 눌러 다른 사람들이 자신의 작업물을 보고 리뷰할 수 있는 방법이 있습니다.

도메인 연결

수정 페이지가 아닌 읽기 전용 페이지를 공유할 수 있습니다. 우상단의 Share 버튼을 눌러 봅시다.

Publish to the web을 활성화하시면 읽기 전용 페이지 링크를 볼 수 있습니다.

다만 링크가 [조직명].gitbook.io/[스페이스명]/ 형태 고정이므로 다른 형태로 URL을 구성하려면 커스텀 도메인을 붙여야 합니다. HostingKR, 가비아 등 여러 외부 업체들이 있고 조건과 여력에 따라 도메인을 구매하시면 됩니다.

도메인을 구매하신 뒤, Share 버튼을 눌러 나오는 창에서 Connect a domain 버튼을 눌러 줍시다.

페이지 접근을 위해 사용할 도메인을 서브 도메인을 포함하여 입력합니다.

DNS 설정이 보입니다. 사용하는 호스팅 서비스의 DNS 설정에서 위와 같은 내용으로 DNS 레코드 하나를 만들어 주시면 됩니다.

레코드를 만드신 뒤 Go Live 버튼을 누르시면 자동으로 세팅합니다. 이후 처음 입력하셨던 링크로 접속할 수 있습니다.

API 작성

위 예시 페이지에서 보시다시피, GitBook은 API Docs 작성을 위한 다양한 도구를 제시합니다. Endpoint별 상세 스펙을 적을 수 있도록 깔끔한 디자인의 UI가 가장 눈에 띕니다. Request/Response Body 등 상세한 정보는 접어서 숨길 수 있도록 만든 점이 편리합니다.

이번 글에서는 GitBook 사용법을 알아보았습니다. 최근 정말 많은 문서 공유/편집 도구가 나오고 있는데, API 문서 작성에 있어 GitBook이 상당히 눈에 띄어 소개해 보았습니다. 여러 도구를 시도해 보는 것도 좋은 것 같습니다.