마크다운 문서화 도입기

created:2016-08-08

updated:2016-10-13

edit

최근에 신규 프로젝트를 들어가면서 DB와 API 설계를 담당하고 있는데 일반적으로 DB 설계는 설계 후 산출물을 가지고 검토를 받고, API는 설계 산출물을 가지고 클라이언트 개발자(앱과 웹) 전달해서 연동할 때 사용하도록 하는 식으로 진행이 된다.

다이어그램이나 그런 것들도 있겠지만, 테이블 상세나 API 상세는 워드 문서(.docx)로 작성되고, 그것을 나 역시 받아서 구현하는 쪽에서만 사용했었다.

그러나, 입장이 달라졌다. 나는 이제 설계를 하고 그것을 내보내야 한다.

워드 문서로 받아 쓰던 입장에서, 이제 만들어야 하는 입장이 되니 그동안 얼마나 만드셨던 분들이 수고를 자처했는지를 알 수가 있었다. 일단 모든 설계가 다 그렇겠지만, (아닐지도 모르겠네?) 개발 직전까지 많은 수정을 거치고, 타인의 검토에 의해서 일부 혹은 전체가 변하기도 한다. 워드 문서로 작성했을 때의 장단점은 아래와 같다.

장점

대부분의 사용자가 이미 포맷과 사용법에 익숙하다.
특정 서식(머릿말, 바닥 글 등)을 이용할 수가 있다.

단점

목차의 문제 : 컨텐츠가 계속 변하기 때문에 목차를 미리 쓰면 문제가 생긴다.
코드 넣기의 번거로움 : 코드를 넣어야 할 경우가 있는데(Request, Response JSON 같은), 그런 부분에서 조금 syntax highlighting이 되었으면 하는 바람이었고, 특정 IDE는 되는 경우도 있었지만, 워드로 붙여넣었을 때 보기 안 좋게 깨지는 경우가 많았다.
창의 이동 : 개발자로서 뭔가 IDE에서 프로토타이핑을 하면서 설계를 하게 되는데, 워드의 경우 창을 이동하거나 하는 번거로움이 있었다.

어떻게 하면 이 문제를 해결할 수 있을까? 하는 생각이 들면서 팀 내에 이 문제에 대해서 공유해서 다같이 고민해보자는 생각보다는, 스스로 이번 프로젝트에 내가 편하게 쓰고 다른 개발자들에게 전달했을 때의 반응들도 한번 살펴보자는 생각을 하게 되었다. 개인적으로 어떤 문제에 대한 합의는 길고, 합의 결과에 대한 시도, 실패, 개선의 프로세스는 생각보다 오래 걸리기 때문에 이렇게 해 보기로 한 것이다.

마크다운(Markdown) 이것 외엔 별다른 대안도 없었다. 그나마 다른 포맷보다 좀 더 문법이 간단하다고 생각했고, 이미 github 에서 사용하고 있기 때문에 github 사용자라면 알 것이라고 생각했다.

그리고 개인적으로 마크다운을 쓰는 가장 큰 이유는 자료(data)와 표현(presentation) 부분을 분리 할 수가 있기 때문이다. 예를 들어 마크다운 문서는 하나의 데이터지만, html, pdf, docx 등으로 변환해서 보여줄 수 있고(오픈소스등에 의해서) 그 안에서 css 등과 같은 역할을 하는 것들을 통해서 하나의 데이터 여러가지 표현을 만들어 낼 수 있다.

그래서 현재의 워드문서에 들어가는 양식들의 대부분을 마크다운 문서로 옮겨서 작성하기 시작했다. 작성하면서 가장 염두해 두었던 부분, 그러니까 작성하는 행위에 대해서 중점을 두었던 부분은 얼마나 빠르게 쓸 수 있는가였다. 이것은 어떤 툴(Tool)을 쓰는가에 대한 문제와 직결되었다.

툴

현재 프로젝트에서 쓰는 IDE는 pycharm 이기 때문에 pycharm에 마크다운 플러그인을 설치해서 쓰기 시작했지만, 처음에는 pycharm 에서 보여주는 마크다운 컬러코드가 마음에 들지 않아서 쓰지 않았다.

그래서 선택했던 것이 Atom 이었다. 이전부터 Atom 의 마크다운 에디팅과 프리뷰 시스템은 아주 마음에 들어 있었다. 그래서 아쉽지만, Atom 을 마크다운 에디팅 툴로 지정하고 설계하는 동안 계속 썼었다.

그렇지만, Atom 은 결과적으로 현재 시점에서는 거의 안쓰는데, 그 이유는 마크다운 문서가 길어지면서 버벅대는 현상을 보이게 되었다. 그리고 Atom을 열고 pycharm 에서 같은 문서를 수정하면 뭔가 문제가 생겼다. 예를 들어 SublimeText 같은 경우 같은 문서를 pycharm 에서 수정하고 SublimeText 에서 보고 그러면, 수정된 내용이 반영되어서 보이고 했는데, Atom은 그렇지 못했다. 아니 정확하게 얘기하면 Atom은 현재 작성 중이었던(Atom에서) 문서를 old 파일명으로 만들어서 보여주었다. 그래서 사용하는 입장에서 다시 Atom으로 돌아와서 작업할 때는 최신의 파일이 아니게 되는 문제가 있었다. (일일이 파일명을 확인하기가 귀찮았다.)

결국 Atom 은 뒤에서 설명하겠지만, 특정 경우에서만 사용하고 현재는 개발하는 IDE인 pycharm 에서 마크다운 문법 하이라이팅 속성을 지정해서 보기 편하게 만들어서 쓰고 있다.

전달을 위한 형식

마크다운(markdown)을 모르는 사람도 있다. 그리고 생각보다 개발자의 유형은 다양하다. 때문에 작성은 마크다운으로 하지만, 누군가에게 전달하기 위해서는 다른 형식으로 변환해서 전달해야 한다고 생각했다. 보편적이고, 다양한 개발자가 알아볼 수 있는 그런 형태로 말이다.

3가지의 전달 포맷을 고려해봤다.

HTML

가장 많이 변환하는 포맷
개발자에게 API문서로 익숙하지 않은 형태(html 파일, 사이트가 아닌)

DOCX

보편적인 형태
그러나 변환하기가 만만치 않다.

PDF

보편적인 형태
생각보다 많은 변환 플러그인/라이브러리가 존재

결과적으로 PDF 를 선택하였는데, 다른 사람이 수정할 수 없는 특성이 있기 때문이었고, 개발자가 아닌 사람도 익숙한 포맷이면서, 생각보다 많은 변환툴들이 있었다.

앞서 Atom 에 대해서 이야기 하면서 여전히 일부 사용하고 있다고 했는데, 사용하는 부분은 PDF 변환 부분으로, 플러그인 markdown-themeable-pdf를 사용하고 있다.

https://atom.io/packages/markdown-themeable-pdf

이 플러그인의 장점은 아래와 같다.

PDF 로 변환되고, 내부적으로 PDF 플러그인으로 변환된 PDF를 바로 Atom에서 볼 수가 있다.
css 를 지정해서 다양한 표현형식을 만들어 낼 수가 있다.
header, footer(header.js, footer.js)를 지원해주고 있어서, 워드파일의 머릿말, 바닥글의 효과를 줄 수가 있다. 예를들면, 머릿글에는 API 문서이면 2016 Project API Reference v0.1 이런식으로 지정할 수가 있다.

문서 전달 후, 느낀점.

앱 개발자에게는 API Reference 를, 다른 개발자에게는 DB 테이블 스키마를 모두 마크다운으로 작성하고 PDF 로 변환해서 전달했다. 일단 전달받는 형식이 PDF 이기 때문에 마크다운 문법으로 작성되었는지 모르고, 익숙한 형식이라서 문서 포맷에 대해서 질문을 하는 사람은 없었다. API 문서는 요청과 응답에 대한 JSON 코드를 포함하는게 좀더 이해하는데 도움이 되는 것 같다.

그렇지만 마냥 행복하지는 않았다. 몇 가지 이슈들이 있는데 아래와 같다.

자동화 이슈
- 생각보다 개발하는 과정에서 DB 와 API의 변경이 잦았다.(현재진행중) 때문에 변경된 내역에 대해서 추적하고 자동으로 마크다운과 PDF문서를 만들어서 배포를 하는 툴이나 시스템이 필요하다고 생각이 들었다.
- DB의 경우, mysql workbench 플러그인으로 python 스크립트를 넣어서 마크다운을 생성하는 스크립트을 커스텀해서 사용했지만, 아쉬운 부분이 많다. 프로젝트에서 sqlalchemy 를 사용하고 있는데, sqlalchemy 에서 뭔가 문서화에 대한 지원이 필요했으면 하는 바램이다.
- API 경우 사실상 수동으로 하고 있다. API 의 경우 postman 을 이용해서 테스트 하고 정리해서 postman collection 형태(JSON)을 문서화 함께 앱개발자에게 전달하고 있는데 기존에 만들어 두었던 postman2md 를 활용해 보는것도 좋을 것 같다는 생각을 했다.
서식의 이슈
- 정확히 마크다운의 이슈라고 보기는 어렵지만, DB의 경우 테이블을 마크다운 문법을 이용해서 표로 그리는데, PDF로 변환하게 되면 페이지가 넘어가는데 애매하게 짤리는 것이 계속 신경이 쓰였다. 만약 워드로 작성할 경우, 애매하게 페이지와 페이지 사이에 어떤 내용이 걸쳐지는 것을 눈으로 확인 할 수 있고, 거슬리는 경우 그냥 엔터키를 쳐서 내려버리면 된다. 그렇지만, 마크다운 문서에는 페이지의 개념이 없기 때문에 작성시에는 별 생각 없이 쓰지만, PDF 로 변환한 후, 페이지에 걸쳐져서 내용확인 어려운 경우에는 <br/> 태그를 넣고, 변환하고, 확인하는 식으로 맞춰나갔다. 가장 마음에 안 드는 부분이긴 한데, 배포하는 나만 신경쓰고 있는게 아닌가 싶기도 하다.

아직 진행중.

마크다운이라는 것이 개발자가 좀 더 쉽게 문서를 쓸 수 있다는 점에서 좋지만, 아직까지 모두가 알고 익숙한 포맷이라는 점 그리고 쓰기 편하다는 점을 애기하기는 어려운것 같다. 이 부분은 상대적으로 느끼는 부분으로 마크다운을 모르는 개발자도 있고, 나 역시 표 같은 경우에는 작성하기 너무 불편했다.

작성-변환-전달로 이어지는 프로세스에 대해서 좀 더 IDE 와 연계하고 실시간으로 담당 개발자들에게 전달할 수 있을지에 대한 고민은 여전히 필요하다.

ps) 이 글을 작성하는 지금도 여전히 문서의 양이 늘어나고 있고, 수작업 수정을 통해서 API 문서를 배포/전달하고 있다.

References

#API #db #dev #markdown #documetation