명세 문서 상태 줄 「구현 전」이 문서 둘을 틀리게 했다

문서를 읽고 성실하게 인용했는데 결론이 틀렸다면, 인용한 사람을 의심하기 전에 인용당한 문서 맨 위 한 줄을 보는 게 낫다.

2026-08-13. 프로젝트 문서 서른다섯 개를 전수로 훑어 낡은 곳을 찾았다. 그중 하나가 이랬다.

어떤 기획 문서에 이런 문장이 있었다.

지금 앱은 한국어·영어뿐이다. 일본어·중국어·스페인어는 설계만 돼 있고 구현 전이다.

그 문장에는 근거까지 붙어 있었다. "명세 문서 확인(8월 4일)". 확인하고 쓴 문장이다.

그런데 실제로는 여섯 개 언어가 이미 돌고 있었다. 두 달 전인 6월 23일에 구현이 끝났고, 언어별 번역 파일도 다 채워져 있었다.

본문은 맞았고 맨 위 줄만 틀렸다

왜 이런 문장이 나왔나. 그 명세 문서 맨 위 줄이 이랬다.

상태: 결정 완료, 구현 전

구현은 그 문서를 쓴 바로 그날 끝났다. 본문에는 구현 내용이 다 들어 있는데, 맨 위 상태 줄만 안 고쳐진 것이다.

그리고 그걸 인용한 문서가 둘 있었다. 기획 문서 하나, 현장 방문 기록 하나. 둘 다 출처를 밝히고 인용했고, 둘 다 틀렸다.

처음엔 「기획 문서가 낡았다」로 처리하려 했다. 문장을 고치고 넘어가면 되는 일로 보였다.

그런데 인용한 쪽만 고치는 걸로는 부족했다. 원인이 다른 데 있었다.

두 문서를 쓴 쪽은 잘못한 게 없다. 명세를 확인했고, 확인한 대로 적었다. 더 조심했어야 한다고 말하려면 — 명세를 읽고도 코드를 따로 확인했어야 한다는 뜻이 된다. 그러면 명세 문서를 왜 두는지 알 수 없게 된다.

답은 둘 다 고치는 것인데, 순서가 있다. 원본을 안 고치면 세 번째 문서가 또 생긴다. 실제로 이미 둘이었고, 석 달 사이에 둘이 됐으니 반년이면 넷이 될 참이었다.

문서 「상태」 줄을 본문과 같은 급으로 취급하기로 했다.

지금까지 나는 문서를 고칠 때 본문을 봤다. 상태 줄은 제목 옆에 붙은 꼬리표 정도로 여겼다. 그런데 남이 읽고 인용하는 건 대개 그 한 줄이다. 본문을 다 읽고 인용하는 경우는 드물다.

그래서 이번에 명세 문서들을 고칠 때 상태 줄부터 손봤다. 「구현 전」이라고 적힌 것들을 실제와 대조해 「구현됨」으로 바꿨다. 그중 셋이 이미 구현이 끝나 있었다.

그리고 낡았던 문서에는 이런 줄을 남겼다.

이 낡은 헤더 때문에 다른 문서 둘이 잘못 적었다 — (문서 이름 둘)

어디로 번졌는지를 적어 둔 것이다. 다음에 이 문서가 또 낡으면 어디를 같이 봐야 하는지가 그 줄에 있다.

고칠 때 한 가지를 더 한다. 이 사실을 인용한 데가 어디인가. 고친 문장에서 특이한 낱말을 골라 전체를 훑으면 대개 나온다. 이번에는 두 곳이 나왔다.

그리고 이왕이면 인용당하기 쉬운 자리부터 본다. 제목 옆 상태 줄, 문서 맨 위 요약, 목록의 한 줄 설명. 사람들이 실제로 복사해 가는 건 거기다.