Confluence 로 책 저술하기 #2

Confluence 로 책 저술 하기 #1 에서는 저술 프로세스와 제가 아는 약간의 테크닉에 대해서 간략하게 설명하고 왜 confluence 를 선택했는지 설명했습니다.

저술 준비

Space 만들기

제일 먼저 할 일은 Confluence 에 저술용 공간을 만드는 것입니다. 기존 공간이 있어도 별도로 분리하는 것이 저술 작업과 페이지 관리가 용이하고 나중에 MS WORD 로 변환시에도 편리하므로 별도의 공간을 생성하고 작업하는 것을 권장합니다.

공개 여부 결정

저술 과정을 공개할지 여부는 저자의 성향에 따라 다르겠지만 저는 공개하고 사용자의 피드백을 받는 건 저술의 품질(오타, 어색한 문장, 실행되지 않는 코드등)을 높이고 독자의 필요에 맞는 책을 쓸 수 있는 장점이 있다고 생각합니다.

또 사전에 저술 내용을 공개하면서 진행하면 해당 내용에 관심있는 사용자의 주목을 받을 수 있고 이는 출간시 마케팅에도 도움이 되므로 공개하는 것을 권장합니다.

만약 저술 과정을 공개하기로 결정했다면 아래의 내용이 도움이 될 수 있습니다.

Space 권한 설정

Confluence 에 계정이 없는 일반 사용자도 볼 수 있어야 하므로 저술 공간은 누구나 읽을수 있도록 설정해야 합니다.

권한 설정은 관리자 콘솔에서 General Permission 에 하면 됩니다.

사용자 피드백 받기

저술을 공개하기로 했다면 사용자가 의견을 남길 수 있어야 반응을 볼 수 있으므로 피드백은 필수적인 기능입니다.

아래는 제가 저술중에 사용자의 피드백을 받아서 원고를 수정한 페이지로 피드백 덕분에 더 양질의 페이지를 작성할 수 있었습니다.

confluence 는 댓글 기능을 제공하지만 익명 사용자가 댓글을 남길 수 있게 할 경우 캡챠 기능이 약하므로 스팸이 많아지는 문제가 있습니다.

저는 소셜 댓글 플랫폼인 disqus 를 사용해서 이런 문제를 처리했으며 설정 방법은 Confluence 와 디스커스(DISQUS) 연동 을 참고하세요.

미완인 페이지는 공개하기 않기

저술 진행시 제목만 써 놓거나 참고 자료만 달랑 있는등 내용이 부실한 페이지를 만들게 될 수 있습니다.

공개할 경우 이런 페이지는 사용자가 보기에 무성의해 보일 수 있으므로 미완인 페이지는 페이지 접근 제한을 사용해서 사용자가 볼 수 없게 잠가 놓고 저술하는 게 좋습니다.

그리고 페이지가 어느 정도 완성되고 공개해도 될 정도가 되었을 때 접근 권한을 풀어 주면 됩니다.

다음/이전 페이지 만들기

이전/다음 페이지를 연결해 주면 사용자가 읽을 때 도움이 많이 되지만 Confluence 는 해당 기능을 제공하지 않으므로 불편하지만 페이지마다 수동으로 이전/다음 페이지를 연결해야 합니다.

저는 사용하는 테마 엔진인 /wiki/spaces/ATS/pages/883622320 에서 {page turner} 이라는 매크로로 이전/다음 페이지 생성 기능을 제공하므로 이것을 사용했습니다.

목차 구성

계층형 페이지 구조

Confluence 가 Mediawiki 등의 다른 위키와 다른 점은 Page 가 계층적 구조라는 점입니다. 이런 특징은 목차와 장, 절등 계층적으로 작성하는 책을 작성하는데 유용한 기능이기도 합니다.

다음은 제가 저술했던 "Laravel 프로그래밍" 책은 메인 페이지인데 계층적 페이지로 구성된 것을 보실 수 있습니다.

아래와 같은 구조는 최상위 페이지의 제목이 chapter 이름이 되며 하위 페이지들은 깊이에 따라 서브 목차로 들어가게 됩니다.

예로 개발 환경 만들기"의 하단의 "vagrant 란" 은 최상위 부모인 "개발 환경 만들기" 보다 2단계가 깊으므로 "2.2.1 vagrant" 라는 목차가 됩니다.

페이지에 숫자 안 붙이기

confluence 의 페이지 기본 정렬 방식은 제목순이며 이때문에 페이지 정렬을 위해 제목마다 1.1, 1.2 등 숫자를 붙이는 경우가 있습니다.

정렬 용도로 제목에 숫자를 붙이면 중간에 페이지가 추가될 경우 이후 페이지에 붙인 숫자를 다 변경해야 하는 문제가 있으므로 사용하지 않는게 좋습니다.

특히 MS Word 로 변환시 자동으로 목차를 생성하고 숫자를 붙여주므로 숫자가 중복되는 문제가 있으니 페이지 정렬이나 이동이 필요할 경우 아래에서 설명하는 기능을 사용하면 됩니다.

페이지 이동을 사용해 목차 변경

Confluence 는 페이지의 이동과 순서 조정이 용이하므로 이 기능을 사용하면 챕터 순서를 자유롭게 조정할 수 있습니다.

만약 목차의 구조나 순서가 변경된다면 "계층형으로 보기(view in hierarchy)" 메뉴에서 이동할 chapter 페이지를 클릭후에 마우스로 끌어다 놓아서 순서를 변경해 주면 됩니다.

목차를 잘 만들기 위한 매크로

목차를 잘 만들려면 한 눈에 하위 페이지의 구성을 볼수 있는게 좋으며 하위 페이지를 표시하는 {children} 매크로가 매우 유용합니다.

이 매크로 사용시 child 의 depth 를 잘 설정하는 것이 중요합니다.

예로 페이지 구성이 복잡한 경우 최상위에서는 모든 자식 페이지를 표시하는 것 보다는 2 나 3 depth 를 주고 하위 페이지를 클릭했을 때 다시 하위 구조를 보여 주는 것이 좋습니다.

참고 자료 관리

저술시에 참고 자료 관리는 매우 중요합니다. 저는 저술시 특성에 따라 참고 자료만 따로 모아 놓은 페이지도 만들기도 했고 또는 저술 페이지내에 직접 참고 자료 링크를 걸기도 했습니다.

어느 방법을 썼든 참고 자료는 원고에서 빠져야 하며 이런 페이지가 있을 경우 사전에 exclude 등 label 을 정한후에 페이지에 label 을 지정하면 나중에 원고 변환시 유용하게 사용할 수 있으며 자세한 내용은 하단의 "WORD 로 변환" 항목에서 설명합니다.

scroll ignore 매크로

한 페이지에 참고 자료를 달았다면 export 시에 페이지내 해당 부분은 출판용 초고에서 제외해야 합니다.

{scroll ignore} 매크로를 사용하고 제외할 콘텐츠를 이 안에 적어주면 MS WORD 로 변환시에 제외됩니다.

예로 기본 컨트롤러(Basic Controllers) 와 라우트 하단에 있는 Ref 아래의 항목은 export 시 제외됩니다.

Scroll macro

MS Word 로 더 편하게 변환하기 위해 scroll ignore 처럼 별도로 제공하는 매크로가 있습니다.

캡션을 달 수 있는 scroll title

그림이나 표의 경우 {scroll title} 매크로내에 위치시키면 캡션을 달수 있으며 이는 WORD 로 export 시 반영됩니다.

scroll office 버그로 "표 1, 그림 1" 로 캡션이 생성되지 않고 "table 1, figure 1" 로 만들어 지므로 초고가 완성되면 수작업으로 캡션 명을 일일이 수정해야 합니다.

그러므로 캡션의 한글 용어 변경은 초고 완성후에 작업하는 게 좋습니다.

페이지 제목을 덮어쓰는 scroll page title

컨플루언스는 기본적으로 하나의 공간에서 같은 제목의 페이지를 가질수 없습니다. (scroll version 같은 별도의 addon 을 사용하면 가능은 합니다.)

일반적인 사용이라면 문제가 없지만 책을 저술할 때는 동일한 제목의 페이지를 만들어야 할 경우가 있습니다. 예로 각 챕터마다 "들어가기" 나 "개요" 같은 제목의 페이지가 있을 수 있습니다.

scroll page title 매크로는 PDF 나 MS WORD 로 변경시 실제 페이지의 제목이 아닌 매크로에 설정한 이름으로 제목을 변경해 주는 기능을 제공하므로 저술할 때 동일 제목 페이지 문제를 해결할 수 있습니다.

WORD로 변환

템플릿 선택

scroll office 는 템플릿 기능을 제공하므로 용도에 맞게 템플릿을 만들어서 활용할 수 있습니다.

include 와 exclude label 사용

자료 조사용 page 등 저술 시점에는 필요하지만 출판물에서는 빠져야 하는 페이지가 있을 수 있습니다. 또는 출판사와 협의 과정에서 이미 저술한 페이지나 chapter 를 제외해야 할 수 있습니다.

이런 페이지가 있을 경우 출판물에서 제외하기 위해 다른 공간으로 옮기거나 아니면 페이지를 삭제를 고민하겠지만 이는 좋은 방법이 아닙니다.

Confluence 는 페이지내에 특정 label 을 달아서 분류할 수 있고 scroll office 는 include label 과 exclude label 기능을 제공하므로 페이지의 이동이나 삭제없이 MS WORD에 포함할 페이지를 넣거나 뺄 수 있습니다.

아래는 exclude 라는 label 이 있는 페이지는 제외하는 설정으로 제외할 페이지는 ^exclude 처럼 제외할 label 앞에 caret 기호를 붙여주면 됩니다.

자세한 내용은 Scroll Office Exporter - Confluence Page 를 MS-WORD로 변환 페이지를 참고하세요.

변환하기

저술 메인(예: 쉽게 배우는 라라벨 5 프로그래밍 )에서 Export to Word 를 선택해서 Word 로 변환합니다.

성공적으로 변환이 끝났으면 word 프로그램에서 문서를 열어서 목차나 내용을 검토후에 수정이 필요하면 해당 페이지를 수정하고 다시 변환 작업을 진행하면 됩니다.

그외 활용 방안

일을 하다보면 혼자 또는 여러 명이 큰 규모의 문서를 공동으로 작성해야 하는 경우가 많이 있습니다.

대표적인 경우로는 저처럼 책을 저술하거나 회사나 학교에서 각종 연구 용역 과제의 보고서를 공동 작성하는 등의 경우입니다.

보고서의 종류와 지향하는 목표에 따라 다르겠지만 규모있는 문서를 체계적으로 협업하여 작성하려면 협업 프로세스를 정립하고 이를 지원하는 적절한 도구가 필요하며 이때도 confluence + scroll plugin 을 유용하게 사용할 수 있습니다.

고객사에 제출할 문서를 Confluence 로 작성하려면 최종 산출물로 HWP 가 아닌 MS-Word 나 PDF 로 제출해도 되는지 고객에게 꼭 확인해야 합니다.