인계 문서에서 빠지면 안 되는 것

맡고 있던 작업을 다른 사람에게 넘기게 되어 인계 문서 HANDOVER.md 를 써야 했다. 무엇을 적을지로 시작하면 구조 설명과 이력까지 끝없이 늘어나서 다 못 쓰고 끝난다.

Open Table of contents

판단 기준 — 무엇을 적을지가 아니라

그래서 무엇을 적을지로 시작하는 것 대신 이것이 없으면 받는 사람이 막히는가로 목차를 잡는 쪽을 골랐다. 이유는 앞의 기준으로는 끝이 없고 뒤의 기준으로는 항목이 유한해져서다. 막히지 않는 것은 코드를 읽으면 나오므로 문서에 없어도 된다.

이 기준으로 추리니 항목이 크게 세 덩어리로 모였는데 사람과 배포와 코드 밖에 있는 것이었다. README 와 겹치는 구조 설명은 링크로만 두었다. 세 덩어리 안에서도 없으면 당장 막히는 항목부터 순서대로 채웠다.

담당자를 적을 때 이름만 나열하면 무엇을 누구에게 물어야 할지가 안 나온다. 그래서 배포 권한·DB 접근·포털 연동 처럼 질문의 종류를 먼저 적고 그 옆에 누구에게 물으면 되는지를 적었다.

사람은 자주 바뀌지만 질문의 종류는 그만큼 자주 바뀌지 않는다. 나중에 담당자가 바뀌어도 그 자리의 이름만 고치면 문서가 계속 유효하다.

우리 코드가 아닌 부분에서 반드시 한 번은 막히므로 외부 솔루션의 연락 창구를 함께 적었다. 이런 것은 우리 코드를 아무리 읽어도 나오지 않는 정보다.

계약이나 지원 범위 같은 것도 알아야 할 때가 있어서 어디를 보면 되는지를 적었다. 우리 것이 아닌 부분일수록 문서에 없으면 스스로 찾아낼 방법이 없다.

배포 방식이 deploy.sh 와 Jenkins 잡과 수동 rsync 세 가지로 나뉘어 있어서 무엇이 어느 경로로 나가는지를 표로 적었다. 한 가지 방식만 알고 있으면 다른 것을 배포해야 할 때 그 자리에서 막힌다.

배포 방법을 적을 때는 rollback.sh 처럼 되돌리는 방법을 언제나 그 옆에 나란히 적었다. 문제가 났을 때 필요한 것은 배포 방법이 아니라 되돌리는 방법이다.

DB 에 들어 있는 프로시저와 트리거는 저장소를 넘겨도 따라가지 않으므로 SHOW TRIGGERS 와 sp_helptext 로 뽑아 따로 적었다. 저장소만 받은 사람은 그런 것이 있다는 사실 자체를 알 수 없다.

계정은 .env 에 어떤 항목이 필요한지만 적고 값은 적지 않았다. 값은 별도 경로로 주는 것이 맞고 문서에 넣으면 그 문서가 있는 곳마다 값이 흩어진다.