소스코드처럼 문서 관리하기

와탭 모니터링

2019년 06월 21일

와탭의 모니터링 서비스는 매우 빠른 주기로 수정되고 업데이트 됩니다. 그리고 이 과정에서 관련 정보와 업데이트 내역을 문서로 반영해 배포하는 것은 서비스 제공자로서 필수 입니다.

현황 및 문제점

다수 개발자들은 버그 픽스나 기능 추가를 즐기지만 이런 변경 내역을 문서로 배포하는 것은 부담스러워합니다. 이것은 개발자 뿐 아니라 Pre-sales와 컨설팅을 담당하는 저 역시 마찬가지입니다. 그리고 문서를 작성하는 과정 자체가 번거롭고 불편하다 보니 고객지원이나 개발에 비해 우선순위를 낮게 두는 경향이 있었습니다.

기존에 사용했던 절차 입니다.

기능 추가 또는 버그 수정
홈페이지 블로그에 릴리즈 노트
MS Word에 내용 추가
MS Word 문서를 PDF로 변환해 홈페이지에 개시하거나 고객에게 전달

이력 관리의 부재

"워드로 작성해 공유드라이브에 업로드 했는데 최종 반영이 안되었어요, 알고보니 최신본은 다른 경로에 있었네요."

"이번에 고객이 문의주신 내용을 문서 어디선가 본것 같은데 찾을수가 없네요."

누락

"작업하고 문서에는 아직 업데이트 안한게 있었던 것 같은데 까먹었네."

"문서 작업은 다음에 몰아서 해야지."

가독성 문제

문서의 틀을 잘 잡아 놓았음에도 수정될 때마다 폰트, 글자 크기, 정렬이 제각각입니다. 대대적으로 손을 봐 놓으면 며칠 만에 또 틀어집니다.

수정의 문제

"옵션 기본값을 바꿨는데 어디어디 문서에 반영해야할지 모르겠어요. 그리고 언제부터 바꿨다고도 적어놔야 할 것 같은데요."

원하는 모습

누가, 언제, 왜, 무슨 내용을 바꾸었는지를 알고 싶었습니다. 누굴 못 믿어서 가 아니라 매번 담당자 찾아가서 물어보는데 시간이 너무 걸렸습니다. 소스코드는 git commit 이력을 보면 쉽게 알 수 있었지만 문서는 그렇지 못했습니다.

최신본을 찾기 위해 공유 드라이브를 찾아 헤매고, pdf로 변환해서 홈페이지에 업로드하고, 고객에게 첨부해 전달하고 하는 등의 소모적인 작업들을 줄여보고 싶었습니다. 사실 콘텐츠를 작성하는 일 보다 이런 부수적인 일들에 더 많은 시간이 소요되었기에 꼭 바꿔보고 싶었습니다.

문서에 반영하는 과정이 번거롭다 보니 몰아서 하려 하고 이 와중에 타이밍을 놓치게 되면 한참이 지난 뒤에야 문서로 반영이 되거나 심지어는 누락이 됩니다. 사실 최신본일까 못 미더운 각각의 워드 파일을 열어 고치고 다시 날짜를 바꿔 저장해서 업로드하는 과정 역시 너무 소모적이었습니다.

문제 해결의 실마리 : Docs as Code

소스코드를 관리하듯 문서를 관리하자는 개념으로 Docs as Code가 있습니다. 이것이 포함하는 바는 다음과 같습니다.

이슈 추적
버전 관리
텍스트 기반
코드 리뷰
자동화된 테스팅

문서화에서 발생하는 문제점을 해결하기 위해 Docs as Code라는 개념이 있는 것을 알았습니다. 이것으로 한줄기 빛을 보았습니다만 와탭이 필요로 하는 고객에게 제공될 '릴리즈 노트', '서비스 가이드'와 같은 문서에 적용할 사례를 찾기는 힘들었습니다.

저희가 원하는 바는 Docs as Code의 정의와 약간의 차이가 있지만 그래도 필요로 하는 기능들을 조합하면 충분히 구현할 수 있겠다는 생각이 들었습니다.

최종적으로는 다음 내용들을 적용하기로 마음 먹었습니다.

공동 작업
버전 관리
텍스트 기반
OSMU(One source multi-use)
CI(Continuous Integration)

적용 과정

도구 선택

코드를 작성하는것과 같이 문서를 작성하기 위해서는 WYSIWYG이 아닌 텍스트기반 편집도구가 필요했습니다. WIKI도 있고 MarkDown도 있지만 다음과 같은 이유로 Asciidoctor를 선택 했습니다.

MarkDown 보다 다양한 문법들이 있다.
Git과 같은 저장소를 사용할 수 있어 공동작업이 가능하다.
결과물을 HTML, PDF와 같이 다양한 형태로 변환할 수 있다.
결과물의 theme를 편집해 원하는 형태로 출력물 디자인이 가능하다.
문서 내에서 다른 문서를 불러올 수 있는 include 태그를 지원한다.
maven, gradle 등을 사용해 빌드할 수 있는 플러그인을 제공한다.

문서 변환

가장 많은 시간을 들인 부분은 기존 워드문서를 Asciidoctor 문서로 변환하는 과정이었습니다.

pandoc을 사용해 1차 변환했지만 표, 이미지와 같이 어쩔 수 없이 사람 손을 거쳐야 하는 부분들이 생길 수밖에 없었습니다. 여러 가지를 방법을 테스트해 봤지만 사실상 완벽한 자동 변환은 어렵다는 것을 인지하고 문법에 익숙해질 겸 사용 가이드를 참고해 기존 문서들을 대대적으로 변환했습니다.
https://pandoc.org/
https://asciidoctor.org/docs/user-manual/