와탭 블로그

전체보기

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

2019년 6월 21일

blog_33_main

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

현황 및 문제점

다수 개발자들은 버그 픽스나 기능 추가를 즐기지만 이런 변경 내역을 문서로 배포하는 것은 부담스러워합니다. 이것은 개발자 뿐 아니라 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/

저장소 구성 및 환경 설정

Text 기반인 Asciidoctor를 선택하니 형상관리가 매우 단순해졌습니다. 단순히 Git에 문서용 저장소를 하나 구성하고 변환한 초기 문서를 Commit 했습니다. 이후 작성을 위해 각자 사용 중인 IDE에 preview 플러그인을 설치했습니다.

Asciidoctor는 Eclipse, VSCODE, IntelliJ 등 사용 중인 개발 환경에서 Preview를 볼 수 있는 플러그인을 지원하므로 워드로 작성할 때와 같이 별도 애플리케이션을 실행할 필요가 없어졌습니다.

https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/

빌드 스크립트 작성

작성한 문서를 html, pdf로 만들기 위한 maven 빌드스크립트를 작성했습니다. 이것으로 배포까지 자동화할 수 있는 환경이 마련되었습니다.

Asciidoctor는 Gradle, Maven, 심지어는 ANT로 결과물을 자동 빌드할 수 있는 플러그인이 제공됩니다.

https://asciidoctor.org/docs/asciidoctor-gradle-plugin/

https://asciidoctor.org/docs/asciidoctor-maven-plugin/

https://github.com/asciidoctor/asciidoctor-ant

디자인

html, pdf 문서의 외형을 디자인 했습니다. 와탭의 능력있는 디자이너가 훌륭하게 만들어 줬습니다.

https://asciidoctor.org/docs/produce-custom-themes-using-asciidoctor-stylesheet-factory/

https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc

배포 자동화
whatap_docs_jenkins 듬직한 젠킨스씨

뭐니뭐니해도 배포하면 Jenkins입니다.

문서를 html, pdf로 빌드 하고, 공유 드라이브에 복사하고, 홈페이지에 배포하는 일련의 작업들은 Jenkins에게 맡겨 두었습니다. Jenkins 빌드 과정에서 사내 공유 드라이브에 업로드하는 일은 rclone을 사용해 쉽게 구현했습니다.

바뀐 모습

Asciidoctor 문법에 적응하는 약간의 수고를 거쳤더니 워드로 작업할때 겪었던 문제점이 사라졌습니다.

일괄 수정
whatap_docs_01 찾고 고치고 Commit

문서가 100개든 1000개든 내용을 찾는 일은 편집기가 대신 해 줍니다. 날짜를 추가하거나 제목을 바꿔 다시 저장할 일도 없습니다.

변경 이력 관리
whatap_docs_02

이제 릴리즈 노트만 보면 제품이 어떻게 변했는지 보입니다. 블로그, 공유드라이브를 넘나들며 작업하지 않아도 되니 문서들은 꾸준히 업데이트 됩니다.

whatap_docs_03

어떤 문서가 추가되고 무엇이 변경되어 언제 배포되었는지는 Jenkins 빌드 이력을 보면 나옵니다.

whatap_docs_04

어떤 내용이 어떻게 변경되었는지는 Git Commit 이력으로 diff 비교할 수 있습니다.

문서 배포 자동화
whatap_docs_05

작성/수정한 문서를 Commit하면 공유드라이브 업로드, 홈페이지 배포와 같은 일련의 과정은 Jenkins가 해줍니다.

고민할 필요 없이 공유 드라이브에 있는 문서가 가장 최근에 빌드된 최신본입니다.

whatap_docs_06

홈페이지도 항상 최근 배포된 최신본입니다.

문서 가독성
whatap_docs_07

문서 템플릿은 전문 디자이너가 만들었습니다. 글 쓰는 사람은 콘텐츠만 고민하면 됩니다. 더이상 문서 외형 때문에 고민하지 않습니다.

html로 제공되는 온라인 문서는 css, javascript까지 적용할 수 있어 디자이너분이 네비게이션 바와 반응형 UI까지 적용해 주었습니다.

whatap_docs_08

PDF 역시 디자이너 작품입니다. 폰트에 신경 많이 썼습니다. 저에게 정색하며 "이탤릭이라도 한글은 기울이는거 좋지 않아요."라고 한 수 가르쳐 주시기도 했습니다.

마무리

Docs as Code 개념을 활용해 문서 작성 프로세스를 바꾼 후 불편했던 점을 해소하고 원하는 모습을 이룰 수 있었습니다.

덕분에 와탭 모니터링 서비스를 시작하거나 사용하는 과정에서 고객이 문의주신 내용들은 기존과 비교할 수 없을 정도로 빠르게 문서에 반영되고 있습니다. 와탭 사용 가이드가 그렇게 관리되고 있습니다.

고객들이 support@whatap.io로 문의주신 궁금점 들은 이전에도 그랬듯이 소중하게 관리하고 있습니다. 그리고 Pre-sales 컨설턴트로서 가장 마음에 드는 점은 고객 질문에 문서를 바로 보완하고 추가해 설명 링크와 함께 답변 드릴수 있다는 것 입니다.

whatap_docs_09
송재진(jjsong@whatap.io)
Pre-sales Consulting TeamLead Consultant, WAS 전문가
<  이전 글

다음 글  >

최신글