기록을 정리하다가 같은 내용이 NOTES.md 와 deploy.md 와 incidents/2023-05.md 세 문서에 각각 적혀 있는 것을 발견했다. 같은 함정에 세 번 걸렸고 세 번 다 앞의 기록을 못 찾아 새로 적은 것이었다.
Table of contents
Open Table of contents
원인 — 앞의 기록을 못 찾은 이유
원인은 셋이었는데 문서가 여러 개라 어디에 적었는지 기억나지 않았고 파일 이름이 주제를 담고 있지 않았다. 그리고 결정적으로 적기 전에 이미 있는지 검색하지 않았다.
같은 것을 여러 번 적었다는 사실 자체가 그것을 못 찾고 있다는 신호다. 그래서 새 항목을 적기 전에 grep -rli 로 문서 전체를 검색하는 단계를 앞에 뒀는데 간단한 일인데도 하지 않고 있었다.
조치 — 한 파일로 모아 합친 결과
반복해서 걸리는 함정을 담는 PITFALLS.md 하나를 만들고 흩어진 세 기록을 옮겨 합쳤다. 각각 다른 각도로 적혀 있어서 합치니 어느 하나보다 나은 설명이 됐다.
항목마다 증상과 SELECT @@time_zone 같은 확인 명령과 주의할 자리를 함께 적었다. 관련 사고 시점도 나란히 적으니 그 함정에 몇 번 걸렸는지가 한눈에 보였고 여러 번 적힌 것이 곧 중요하다는 표시였다.
해결 — 기록으로 막지 않고 고치기
세 번 걸렸다면 기록으로 막을 것이 아니라 구조를 고쳐야 하는 단계였다. 두 가지 방법이 있었는데 PITFALLS.md 항목을 더 눈에 띄게 다듬는 것과 config/app.php 의 timezone 과 모델 $casts 로 프레임워크가 시각 변환을 담당하게 하는 것이다. 뒤쪽을 골랐다. 이유는 기록은 읽은 사람만 막고 설정은 안 읽은 사람도 막아서다. 대신 옛 코드의 수동 변환 자리를 찾아 하나씩 걷어내는 기간을 감수했다. 설정하니 손으로 변환할 일이 없어졌다.
다만 기록은 그대로 남겼는데 옛 코드에는 아직 setTimezone() 수동 변환 자리가 남아 있었기 때문이다. 고친 것과 남은 것이 공존하는 동안에는 기록이 여전히 필요하다.
반복 항목을 세어 찾기
같은 방식으로 다른 반복 항목도 찾으려고 grep -rlc 로 몇 개 낱말이 몇 개 파일에 나오는지 셌다. 권한 이 여섯 파일에 나왔고 읽어 보니 그중 셋은 같은 이야기였다.
여러 파일에 걸쳐 나오는 낱말을 세는 것만으로 통합 후보가 드러났다. 문서가 늘어날수록 이 집계가 정리 대상을 고르는 값싼 기준이 된다.
검증 — 읽히는 문서로 만들기
한 곳에 모아도 읽히지 않으면 소용없어서 새로 온 사람에게 읽게 하고 어디서 헷갈렸는지 물었다. 두 항목이 이해되지 않는다고 했는데 내가 아는 것을 전제하고 썼기 때문이었다.
아는 사람만 읽히는 문서는 읽히지 않는 문서와 같으므로 전제를 풀어 다시 적었다. 시간이 지나 해당 없어진 항목은 지우지 않고 ~~취소선~~ 과 사유를 붙여 표시했는데 지우면 그런 것이 있었다는 사실 자체가 사라지고 옛 코드를 볼 때는 여전히 필요하기 때문이다.
정리
- 같은 것을 여러 번 적었다면 앞의 것을 못 찾고 있다
- 적기 전에
grep -rli로 먼저 검색한다 - 흩어진 기록을
PITFALLS.md한 곳으로 모은다 - 여러 기록을 합치면 각각 다른 각도라 더 나아진다
- 몇 번 걸렸는지 적으면 중요도가 드러난다
- 세 번 걸렸으면 기록이 아니라 구조를 고친다
- 여러 파일에 나오는 낱말을 세어 통합 후보를 찾는다
- 해당 없어진 항목은 지우지 않고 표시한다