채널 연동 규격서 spec-*.md 를 여러 벌 쓰게 됐는데 매번 처음부터 썼다. 세 벌을 쓰고 나서 셋의 구조가 서로 다르다는 것이 눈에 띄었고, 쓸 때마다 무엇을 적을지를 다시 생각하고 있었다는 것도 그때 알았다.
Table of contents
Open Table of contents
배경 — 목차 비교로 드러난 것
세 문서의 ## 줄만 grep 으로 뽑아 나란히 놓고 봤더니, 이름이 다른데 같은 것을 말하는 절이 여럿 있었다. 개요와 목적과 배경이 같은 자리이고, 인증과 사전 준비가 같은 자리이며, API 목록과 요청·응답과 상세 규격이 같은 자리였다.
$ for f in docs/spec-*.md; do echo "=== $f"; grep '^##' "$f"; done이름만 다른 것을 걷어내고 나니 그 아래에서 진짜 차이가 드러났다. 어떤 문서에는 시험 방법과 일정이 아예 없었고, 어떤 문서에는 error_code 목록이 없었으며, 또 어떤 문서에는 OAuth 인증 상세와 담당자가 없었다. 셋 다 무언가 빠져 있었는데 각각만 보고 있을 때는 그것이 안 보였다.
조치 — 공통 여덟 절
셋에서 나온 절을 합치니 여덟 개가 됐다. 개요와 사전 준비와 연동 방식과 API 상세와 오류 처리와 시험과 일정과 담당이다. 어느 한 문서에도 여덟 개가 다 있지는 않았고, 합쳐 놓고 나서야 각 문서에서 빠진 자리가 어디인지 대조가 됐다.
이걸 그대로 spec-template.md 빈 틀로 만들었다. 두 가지 방법이 있었는데 가장 잘 쓴 문서 하나를 복사해 틀로 삼는 것과 셋의 합집합으로 새 틀을 만드는 것이다. 뒤쪽을 골랐다. 이유는 어느 하나도 여덟 절을 다 갖고 있지 않아서다. 대신 그 문서에만 있던 세부 서술을 잃고 빈칸부터 다시 채우는 것을 감수했다. 각 절 아래에 채울 항목을 콜론으로 남겨 두고 사전 준비에는 체크박스를 뒀다.
## 3. 연동 방식
프로토콜:
인증:
형식:
문자 인코딩:
시간대: 문자 인코딩 과 시간대 를 넣은 것은 그 둘 때문에 실제로 문제가 났던 적이 있어서다. 규격서에 안 적혀 있으면 양쪽이 서로 다른 값을 가정한 채로 붙이고, 그러면 붙고 나서야 어긋난다.
검증 — 빈칸이 곧 질문 목록
틀을 놓고 채우기 시작하니 모르는 것이 한꺼번에 드러났다. UTF-8 인지 EUC-KR 인지와 KST 인지 UTC 인지와 재시도 기준 셋이 비었고, 그 셋을 한 번에 물었다. 전에는 문서를 만들다가 막힐 때마다 하나씩 물어서 왕복이 그만큼 늘어났다.
상대 쪽에도 같은 spec-template.md 를 보내면서 빈칸으로 남는 부분은 우리가 정하겠다고 적어 보냈다. 채워서 오니 우리가 정리할 것이 줄었다. 한 곳은 이미 자기 규격서가 있어서 그것을 받아 우리 틀에 옮겨 적었는데, 옮기는 과정 자체가 빠진 항목을 찾아 주는 절차가 됐다.
주의 — 틀은 쓸 때마다 자란다
새 연동을 하면서 틀에 없던 것이 둘 나왔는데 분당 호출 한도와 p95 응답 시간 기준이다. 둘 다 넣어서 다음 규격서는 열 절이 됐다.
같은 방식으로 incident-template.md 와 이관 계획서와 점검 결과서에도 틀을 만들었고 장애 보고서가 특히 값을 했다. 급한 상황에서 무엇을 적어야 하는지를 생각하지 않고 빈칸만 채우면 되기 때문이다. 급할 때 쓰는 문서일수록 틀이 있어야 한다는 것이 여기서 나왔다.
원인 — 필수와 선택의 분리
다만 절이 열둘까지 늘어나자 채우는 것 자체가 부담이 됐고 실제로 다 안 채우고 넘기는 일이 생겼는데 그러면 틀이 있으나 마나가 된다.
그래서 필수와 선택을 나눴다. 개요와 연동 방식과 API 상세와 오류 처리와 담당은 필수 로 두고, 시험과 일정과 한도와 p95 기준은 선택 으로 뺐다. 선택인 절에는 그것이 선택이라는 표시와 어떤 경우에 채우는지를 주석으로 달았다.
## 6. 시험 (선택)
<!-- 시험 환경이 있는 경우만 -->표시를 하니 빈칸으로 남겨도 되는 자리가 명확해졌는데 전에는 빈칸이 전부 미완성으로 보여서 채우거나 지우거나 해야 했다. 작은 연동은 필수만 채우고 큰 연동은 전부 채우는 식으로 갈렸고, 필수를 작게 둔 쪽이 실제로 더 채워졌다.
정리
- 비슷한 산출물이 여럿이면 목차만 뽑아 나란히 놓고 비교한다
- 이름이 달라도 같은 자리를 말하는 절이 있어서 먼저 그것을 걷어낸다
- 공통을 합쳐 놓으면 각 문서에서 빠진 자리가 대조로 드러난다
- 틀의 빈칸을 채우다 보면 모르는 것이 한꺼번에 나와서 한 번에 물을 수 있다
- 상대에게도 같은 틀을 보내면 받아서 정리할 것이 줄어든다
- 남의 문서를 우리 틀로 옮기는 과정 자체가 누락을 찾아 준다
- 틀은 한 번 만들고 끝이 아니라 새 사례에서 나온 항목을 더하며 자란다
- 급할 때 쓰는 문서일수록 틀이 값을 한다
- 틀이 커지면 안 채우게 되므로 필수를 작게 두고 나머지는 선택으로 표시한다