세 번 따로 적힌 같은 함정

기록을 정리하다가 같은 내용이 서로 다른 세 문서에 각각 적혀 있는 것을 발견했다. 같은 함정에 세 번 걸렸고 세 번 다 앞의 기록을 못 찾아 새로 적은 것이었다.

Open Table of contents

앞의 기록을 못 찾은 이유

원인은 셋이었는데 문서가 여러 개라 어디에 적었는지 기억나지 않았고 파일 이름이 주제를 담고 있지 않았다. 그리고 결정적으로 적기 전에 이미 있는지 검색하지 않았다.

같은 것을 여러 번 적었다는 사실 자체가 그것을 못 찾고 있다는 신호다. 그래서 새 항목을 적기 전에 문서 전체를 검색하는 단계를 앞에 뒀는데 간단한 일인데도 하지 않고 있었다.

반복해서 걸리는 함정을 담는 파일 하나를 만들고 흩어진 세 기록을 옮겨 합쳤다. 각각 다른 각도로 적혀 있어서 합치니 어느 하나보다 나은 설명이 됐다.

항목마다 증상과 확인 명령과 주의할 자리를 함께 적었다. 관련 사고 시점도 나란히 적으니 그 함정에 몇 번 걸렸는지가 한눈에 보였고 여러 번 적힌 것이 곧 중요하다는 표시였다.

세 번 걸렸다면 기록으로 막을 것이 아니라 구조를 고쳐야 하는 단계였다. 프레임워크가 시각 변환을 담당하게 설정하니 손으로 변환할 일이 없어졌다.

다만 기록은 그대로 남겼는데 옛 코드에는 아직 수동 변환 자리가 남아 있었기 때문이다. 고친 것과 남은 것이 공존하는 동안에는 기록이 여전히 필요하다.

같은 방식으로 다른 반복 항목도 찾으려고 몇 개 낱말이 몇 개 파일에 나오는지 셌다. 권한이 여섯 파일에 나왔고 읽어 보니 그중 셋은 같은 이야기였다.

여러 파일에 걸쳐 나오는 낱말을 세는 것만으로 통합 후보가 드러났다. 문서가 늘어날수록 이 집계가 정리 대상을 고르는 값싼 기준이 된다.

한 곳에 모아도 읽히지 않으면 소용없어서 새로 온 사람에게 읽게 하고 어디서 헷갈렸는지 물었다. 두 항목이 이해되지 않는다고 했는데 내가 아는 것을 전제하고 썼기 때문이었다.

아는 사람만 읽히는 문서는 읽히지 않는 문서와 같으므로 전제를 풀어 다시 적었다. 시간이 지나 해당 없어진 항목은 지우지 않고 취소선과 사유를 붙여 표시했는데 지우면 그런 것이 있었다는 사실 자체가 사라지고 옛 코드를 볼 때는 여전히 필요하기 때문이다.