협업하여 문서 작성하기

Gitbook은 직관적으로 작업할 수 있는 인터페이스를 제공하기 때문에 문서 퍼블리싱 하기에 기술된 절차를 참고하시어 공유문서 편집을 진행하시길 바라며, 다른 소스관리툴 등의 경험으로 인해 Gitbook의 협업체계가 혼동스럽거나, 보다 자세한 이해가 필요할 경우 본 장을 참고하시길 바랍니다.

1. Gitbook의 협업구조

현재 Merge된 Main 버전에서 새로운 draft버전(=Branch 개념)으로 협업을 진행하려면 'change request' (= 'Edit 버튼 누르기')를 이용해 Main에서 분리된 새로운 draft 버전에서 작업을 하고, 작업을 완료한 후 Main으로 'Merge'할 수 있습니다.

웹에 퍼블리싱 중인 Space는 'change request'를 통해서만 새로운 draft 버전 콘텐츠를 편집할 수 있습니다.

현재, 공유문서(CDN document, Tech support, Knowledge base)는 웹에 퍼블리싱 중인 Space들로 'change request'를 통해서만 편집이 가능합니다.

2. 'Change request'(=Edit)를 이용해 협업하기

Gitbook의 버전관리 방법은 소스관리 툴인 Git의 Main과 branch 버전 관리와 유사한 개념을 적용하고 있습니다.

사내 공유문서와 같이 퍼블리싱되어 있는 Space에 신규 콘텐츠를 추가하거나 수정하는 작업은 'Change request'를 통해 이루어 집니다. 'Change request'는 'Edit in branch' 의 개념으로 main 버전에서 새로운 draft 버전을 생성하고 작업완료 후 'Merge'를 이용해 새로운 Main 버전으로 릴리즈 됩니다.

아래 그림의 초록색은 Space의 우측상단에 표시되는 수행 버튼을 표시하며, 해당 버튼을 수행 시 Main과 Change request(Branch 개념)가 어떻게 관리 되는지를 보여줍니다.

Edit

Space의 우측 상단의 'Edit' 버튼을 누르면 새로운 'Change request'를 시작합니다. 'Change request'를 통해 저자는 Main에서 새로 Branch한 draft 버전에서 편집을 수행할 수 있습니다. ('Change Request'는 Git의 Main 버전에서 새로운 Branch 분기와 유사한 개념)

Change request를 수행하는 또 다른 방법으로 New change request 버튼을 누르면 됩니다.

• Space의 우측 상단의 Change Requests를 클릭 후, 오른쪽 슬라이드 패널에서 'New change request' 버튼을 누릅니다.

Submit for review

'Edit' 버튼을 누른 후 Change reqeust(=branch)로 작업중이던 draft 버전의 편집을 완료하고, 동료검토를 위해 'Submit for review'를 수행합니다.

'Submit for review'를 수행하면, 해당 Space의 공동 편집자에게 알림메일이 전송됩니다.

이후 해당 Change reqeust는 'In review' 상태로 전환되며, 해당버전을 다시 재 편집하기를 원할 경우 'In Review' 패널에서 찾아서 편집을 계속할 수 있습니다.

Merge

Change reqeust(=branch)로 작업 중이던 버전을 Main 버전으로 릴리즈 합니다.

웹에 퍼블리싱되어 있는 문서의 경우 'Merge'가 완료됨과 동시에 웹 퍼블리싱이 완료 됩니다.

별도의 동료검토를 통해 퍼블리싱(=Merge)이 필요한 'CDN Document'와 'Tech Support' 스페이스에서는 'Merge' 버튼을 보실 수 없습니다.

계정의 소유자가 'Editor' 이상의 권한을 가져야 'Merge'를 수행할 수 있습니다.

Update

특정 스페이스에서 Change request(=branch)로 작업중에 다른 버전의 'Merge'가 발생할 경우 해당 Space의 우측 상단에 'Update' 버튼이 생깁니다.

'Update'를 수행하여 최종 'Merged'된 내용을 통합하여 계속 편집작업을 진행하실 수 있습니다.

'Update'를 수행하지 않고, 편집 완료 후 'Submit for review' 혹은 'Merge'를 수행하여도 Gitbook은 자동으로 최종 'Merged'된 내용을 통합합니다.

3. Draft 버전을 이용한 문서 관리

• 편집 중이던 페이지 창을 닫거나 다른 페이지로 이동한 경우

• Review(Submit for review) 요청 혹은 Merge 하기 전, 장시간 문서 편집이 필요한 경우

• 특정 Draft 버전을 여러 동료 작성자와 함께 동시에 편집할 경우

편집 중이던 창이 닫거나 다른 곳으로 이동했을 경우 아래의 안내에 따라 이전에 작업하던 'Draft' 버전을 찾아 작업하시길 바랍니다. 아래 절차를 수행하지 않고 바로 'Edit' 버튼을 눌러 편집을 수행하게 되면, 이전 작업내용과 연결하여 작업할 수가 없으며, 또한 많은 'Draft' 버전이 발생하여 버전 관리에 불편함이 발생합니다.

또한, 특정 Draft 버전을 여러 명이 동시에 편집해야할 경우, 해당 Draft 버전을 공유하여 동료 작성자와 함께 편집을 수행할 수 있습니다.

* 편집 중인 창을 닫거나 편집하던 창이 사라진 경우

해당 스페이스의 sub-navigation 왼쪽 상단의 'Change Requests'탭을 클릭 후 오른쪽의 'Draft' 탭에서 이전에 편집중이던 작업페이지를 불러와 계속 편집을 할 수 있습니다.

새로운 편집을 시작 시 문서의 draft 버전에 설명을 추가해두면, 편집 중단 된 곳으로 복원하기 수월합니다. git commit -m " commit 포인트에 관한 설명"이라고 이해하시면 편리합니다.