GitBook 라이브 문서 공유 나도 한번 사용해볼까?

GitBook이 도대체 뭐인가

GitBook( https://docs.gitbook.com / )사이트 설명에 따르면 "GitBook은 팀이 제품에서부터 시작하여 내부 지식 기반 및 API에 이르기까지 모든 것을 문서화할 수 있는 최신 문서 플랫폼이다."라고 설명하고있다. 즉 모든 문서화작업을 온라인상에서 쉽게 제공할하는 플랫폼이란 얘기다.

 

그러면 이 온라인 문서 작성 플랫폼을 어떻게 사용할 수 있는가? 이를 간단히 몇가지 핵심 사항으로 정리하여고 합니다.

 

GitBook으로 무엇을 할 수 있는가?

1. 문서를 배포하기 앞서 작성한 문서를 협업 팀원들간에 혹은 리뷰자들에게 사전 배포하여 정해진 기간 아무때나 평가 피드백을 받을 수 있다
2. 지식기반 문서를 공개적으로 혹은 개인적으로 다른 사람과 공유할 수 있으며 GitBook사용자가 아닌 사람들에게 비밀 링크로도 공유가능하다.
3. 실시간 협업 문서 작업을 WYSIWYG(위지위그- 보면서 편집) 편집기를 사용해 풍부한 컨텐츠와 텍스트를 라이브로 즐길 수 있다.
4. 회사나 개인의 branding에 맞추어 문서 작업 공간를 커스터마이즈 가능하여 작성한 문서에 가치를 더할 수 있도록 해준다.

 

몇가지 use cases를 소개하면 다음과 같다

1. 제품에 대한 문서화 작업 - 제품 문서 작업은 API, 제품, FAQ, 사용자 가이드에 대한 멋진 문서를 만들 수 있는 장소를 제공한다
2. 지식 기반 문서 작업 - GitBook은 팀, 모범 사례 및 생각을 위한 공간을 제공한다.
3. 개인 노트 정리 작업 - 자신의 문서를 체계화하고 아이디어를 정리하여두었다가 나중에 팀과 아이디어를 공유하고 추적할 수 있는 설계 장소를 제공한다.

 

그러면 프로그래밍을 강의하는 지침서를 만들어 학생들과 온라인 상에서 공유하는 문서화 작업을 한다고 가정해봅시다. 이전에는 아마도 문서 작업을 워드나 아래아 한글 혹은 파워포인트 같은 문서 작업 툴로 정리하고 이를 pdf 파일로 변환하여 웹사이트나 LMS(Learning Management System, 학습관리 시스템에 수업 보조 자료로 업로드하여 학생들에게 공유하는 방식이 대부분이었다. 그러나 지금은 시대가 바뀌었다. 라이브로 지식 기반 지침서(Guidebook, Help docs, Product Manuals, API 사용법 등)만들어 웹사이트 실시간 공유가 가능하다. 이 방법을 간단히 예로들어 소개하려고 합니다.

기본 전제: 학생들에게 프로그래밍 수업을 등기 위한 필요한 도구와 그 설치 방법등을 설명하는 문서를 만들어 공유하는 것

방법 : GitBook 문서 작업 플랫폼 사용

웹사이트 : 커스텀 도메인 사용

 

기본 준비 사항

-GitBook 계정을 새로 만들거나 GitHub계정과 연동한다

-개인 사이트 운영(예를들면 tistory, blogger, naver 등)나 웹 호스팅 계정

 

계정을 만들어 로그인하면 나타나는 화면

로그인후 처음 나타나는 화면 왼편에 보면 New Org + 버튼이 보인다. 여기를 눌러 기관 등록을 하면 기관별 문서 관리가 용이하다. Settings에 가서 로고를 등록시킬 수 있다.

기관 버튼을 누르고(우리의 경우 Keiin) 난 다음 + Create a new space 버튼을 눌러 작업한 문서 공간(space) 이름은 지정하여 만든다. 우리는 간단히TITLE은 Keiin International Institute라고 입력한다.

반응형

다음 Keiin International Institute 문서 공간 버튼을 누르면 문서 작업 구성 창으로 이동되며 기본으로 Initial Page가 뜬다. 문서 작업 공간으로 이동한후 왼쪽 Table of Contents에서[New +]를 눌러 목록을 작성한다.

이제 목록의 컨테츠는 한개의 문서 작성 페이지가 된다. Installation Guide 페이지를 열어 편집한다. 문서 문집기가 제공하는 카드 엘리먼트는 다양한 문서 편집 카드 방식을 제공한다.

이제 편집이 끝났다고 가정하고 작성된 GitBook 문서를 인터넷 웹페이지에 공유하고 싶다면 몇가지 단계가 필요하다

단계 1: 웹사이트에 공유하려는 문서 이름을 정한다: 우리의 경우 helpprogramming으로 했다. 원하는 이름으로 임의적으로 지정 가능하다

단계 2: GitBook 대시보드(우리의 경우 기관 이름이 Keiin)로 가서 맨 왼쪽 아이콘 메뉴 밑으로 가면 Advanced 옵션 메뉴가  보인다. 여기를 클릭한다. Custom Domain 을 클릭하면 도메인 주소 입력창이 나타난다. 사용하려는 도메인 이름은 koida.tech 이다 . 이 부분은 여러분이 회사나 개인이  호스팅하는 도메인이 될 수 있다.

[Configure] 버튼을 누르면 우리의 경우 helpprogramming.koida.tech라고 입력한다.  그런데 아직 우리는 도메인을 우리가 운영하는 사이트에 등록하지 않았다. 먼저 해야할 일은 호스팅하는 도메인에 로그인하여 위 helpprogramming.koida.tech 을 DNS configuration에서 도메인을 등록해야한다. 허용되는 도메인 형식은

www.example.com 혹은 docs.example.com  이다.

자 이제 여러분이 호스트 사이트나 개인 웹사이트에 로그인하였다고 가정하고 진행합니다.  호스팅 사이트의 메인 호스팅 도메인 우리의 경우 koida.tech,  DNS Settings으로  가서 아래와 같이 CNAME record를 추가해야한다.

여기까지 성공적으로 CNAME Record를 호스틴 도메인에 등록 완료했다면 다시 GitBook 편집 페이지로 가서 Keiin (Org)  로 가서 Advanced 메뉴 버튼을 누르고 Custom Domain을 선택하고 helpprogramming.koida.tech를 입력하고 Configure버튼을 누른다. COnfigure your DNS 팝업창이 나타나면서 연결을 시도한다. 만일 여러분이 아직 문서이름에 대한 cname record를 호스팅 도메인에 등록하지 않은 연결 할 수 없다는 메세지가 뜬다. 이르 단계적으로 그림으로 보였으니 참고하기 바랍니다.

 

 

 

 

제대로 CNAME Record를 등록하였다면 오류없이 연결되었다고 메세지가 나타난다.

단계 3: 이제 온라인 웹사이트에 문서를 등록되었는지 확이하는 것은 웹 사이트를 방문하는 것과 동일하다. 우리의 경우 helpprogramming.koida.tech 을 웹브라우져창에 입력하면 아래와 같이 작성된 문서를 웹사이트에서 라이브로 볼 수 있다Installation Guide - Keiin International Institute (koida.tech)).