저는 nodejs/undici에서 작고 범위가 명확한 기여를 찾다가 하나를 발견했습니다. 여덟 개의 내장 인터셉터(dump, retry, redirect, decompress, responseError, dns, cache, deduplicate)에 대해 전용 API 문서가 전혀 없었습니다. 언급만 지나치게 되어 있을 뿐, 각각이 무엇을 하는지, 어떤 옵션을 받는지, 또는 어떻게 조합하는지를 설명하는 단일 페이지가 없었습니다. 명확한 공백이었고, 해결책도 명확했습니다. 바로 문서를 작성하는 것이었죠.

저는 당연한 일을 했습니다. docs/docs/api/Interceptors.md를 만들고, 인터셉터별로 시그니처와 예시가 담긴 섹션을 작성했으며, 이를 site.json의 사이드바에 연결하고 PR #5446을 열었습니다. 임무 완료라고 생각했습니다.

돌아온 리뷰 코멘트는 제가 작성한 내용이 잘못되었다는 것이 아니었습니다. 제가 알아차리지 못한 무언가에 관한 것이었습니다. 바로 Dispatcher.md에 이미 ## Pre-built interceptors 섹션이 있었고, 이 섹션이 대부분의 내용을 다루고 있다는 것이었습니다. 다만, 인터셉터별 전용 페이지가 없었을 뿐, 그리고 완전히 완벽하지는 않았습니다. 제 새 파일은 공백을 메우기보다는, 두 곳에 걸쳐 잘못되게 중복하고 있었습니다.

제가 그것을 알아차리지 못한 이유

저는 시작하기 전에

제가 댓글을 받았을 때 가장 먼저 떠오른 생각은 두 섹션을 모두 유지하고 더 잘 교차 연결하는 방법을 알아내는 것이었습니다. 그것이 잘못된 직관이며, 왜 그런지 언급할 가치가 있습니다. 그것은 첫 번째 초안이 잘못된 문제를 해결했다고 인정하기보다는 자신의 이전 작업을 보존하려는 본능입니다. 겹치는 두 섹션을 교차 연결한다고 해서 중복을 제거하는 것은 아니며, 단지 중복을 찾기 더 쉽게 만들 뿐이고, 이는 고치는 것과는 다릅니다.

리뷰어(metcoder95)가 실제로 요청한 수정 사항은 직설적이었습니다. Dispatcher.md에서 ## Pre-built interceptors 섹션을 거의 완전히 삭제하고, 새로운 전용 페이지로 짧게 연결하는 포인터로 대체하며, 이제 제거된 섹션으로 링크되던 모든 것을 고치라는 것이었습니다.

-
## Pre-built interceptors
-

Undici는 다음 인터셉터를 제공합니다:
...

해당 커밋의 순수 차이(Net diff)는 -285줄, +3줄이었고, 게다가 방금 삭제한 섹션 내부의 앵커를 가리키던 이제 유효하지 않은 내부 링크 참조 9개를 제거하고, 대신 dispatcher.compose() 섹션에서 새 페이지를 가리키는 새로운 링크 1개를 추가하는 것이었습니다. 이렇게 한 커밋(fbac28a1)은 원래 PR보다 작고 흥미롭게 작성하기는 어렵지만, 실제로 기여를 좋게 만든 커밋이었습니다.

일반화할 수 있는 부분

문서를 추가하는 것은 기존 문서를 검토하며 중복을 확인하는 것과는 다른 방식으로 생산적이라는 느낌을 줍니다. 새 페이지를 작성하면 마지막에 눈에 보이는 긍정적인 결과물이 있습니다. 하지만 만약 제대로 한다면, 당신의 새 페이지가 오래된 문서와 중복되는지 확인하는 과정은 아무런 결과물도 남기지 않습니다. 애초에 중복을 만들지 않기 때문에, 그리고 아무도 당신이 배포하지 않은 버그를 보지 못하기 때문입니다.

그러한 비대칭성(asymmetry)이 바로 실수를 저지르기 쉽고 반복하기 쉬운 이유입니다. '새 문서 작성' 과정에는 스스로 구축하지 않는 한, 같은 내용을 다루는 기존 문서를 찾아보라고 유도하는 자연스러운 검토 지점(checkpoint)이 없습니다. 이번 PR 이후로 제가 실제로 어떤 문서 PR을 열기 전에 사용하는 검토 지점은 지루하지만 기계적입니다. 바로 기존 문서 트리를 검색하여 내가 쓰려는 주제어뿐만 아니라 _특정 기능 이름_으로 grep하는 것입니다. 그리고 일치하는 모든 파일을 끝까지 읽습니다. 단순히 일치하는 줄만 보는 것이 아닙니다. 예를 들어, grep -rn "interceptor" docs/를 실행하면 Dispatcher.md가 검색될 것입니다. 첫 번째 결과에서 멈추지 않고 그 뒤의 내용을 읽는 부분이 제가 건너뛰었던 부분입니다.

이것을 포착한 리뷰어는 제가 사실적으로 틀린 것을 작성했다는 문제가 아니었습니다. 제 원래 Interceptors.md에 있는 모든 내용은 정확했습니다. 문제는 PR 자체가 필요 이상으로 많았다는 것이고, 문서가 더 많이 있다고 해서 자동으로 더 좋은 문서는 아닙니다. 같은 8개의 인터셉터에 대한 두 가지 설명이 두 파일에 존재한다는 것은 다음번에 인터셉터 동작을 업데이트해야 하는 사람이 둘 다 업데이트하는 것을 기억해야 한다는 의미이며, 결국에는 그렇게 하지 못하게 되고, 그러면 두 곳 중 한 곳의 문서가 잘못되게 되지만 아무도 알아차리지 못하다가 누군가 그것에 대해 이슈를 제기할 때까지 시간이 걸립니다.

제가 작성한 285줄을 삭제하는 것은 그 내용에서 버그를 수정하는 것보다 더 큰 양보처럼 느껴졌습니다. 그럴 필요가 없었습니다. 병합된 PR이 제가 열었던 PR보다 좋으며, 특히 제가 추가했던 대부분의 내용이 리뷰를 통과하지 못했기 때문에 더 좋습니다. 만약 좋은 문서 기여에 대한 당신의 측정 기준이 '추가된 줄 수'라면, 이 PR은 뒤로 물러난 것처럼 보입니다. 하지만 그렇지 않습니다. 두 개의 절반만 맞는 진실의 출처에서 하나의 완전한 출처로 이동했고, 이것이 바로 실제 목표이며 줄 수는 아닙니다.