🌳ASH84

Maker, Developer, Adventurer 🤩

마크다운 문서화 도입기

2016-08-08

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

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

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

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

장점

단점

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

마크다운(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

DOCX

PDF

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

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

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

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

문서 전달 후, 느낀점.

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

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

아직 진행중.

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

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

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

References


#API  #db  #dev  #markdown  #documetation