DongHyeonkaandClaude Fable 5.1
9d2a3725c5
리뷰 두 건을 반영했다. 계약 - tech-log-tree.json 하나가 분해 계약이자 색인이다. 사람이 읽는 트리·Node Specification· 후보 대장은 없어졌고, 문서에 남아 있던 그 개념을 걷어냈다 - candidateScope — 후보를 찾는 SSOT 범위. 접어 넣은 제2부·제3부는 근거이지 후보가 아니다 - sourceRepository — 분석한 저장소의 경로·리비전·판단 근거. 리비전을 모르면 null 로 두고 지어내지 않는다. 갈래가 여럿이면 revisions - 검사기: 계약 미채택·PENDING·PROMOTE↔글감 양방향·candidateScope·sourceRepository 를 error/warn 으로 센다. 옛 스키마도 검사를 피하지 못한다. 테스트 22 → 31 기록 쓰기 - 템플릿 5종에 source·sourceRevision·topicName, Question 에 닫는 조건, 본문 없는 종류에서 assets 제거. 고정 절 개수 삭제 - check_evidence.mjs — 인용한 코드가 SSOT 에 있는지, 앵커가 SSOT 를 가리키는지, 제목이 계약과 같은지, 리비전이 저장소에 있는지. 게시된 기록에서 SSOT 와 다른 URL 을 잡았다 문체 - 문체 규칙의 정본을 ai-tells.md 로. explaining.md 의 질문체 제목·절 끝 대조 반복·그림 예고 규칙을 삭제해 충돌을 없앴다. 첫 절 「설명 뒤에 평가를 붙이지 않는다」에 지우는 사례 네 유형 - voice 스킬의 「독자 쪽을 본다」를 자료에 오독 기록이 있을 때로 좁히고, 평가만 더한 예시를 교체 - check_prose: 안내 문장을 요구하던 경고 제거, 문장이 끝나지 않은 채 문단이 끝나는 조각 검사 추가 Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
7.6 KiB
다섯 가지가 여섯 편에서 어떻게 쓰였나
원문은 ../../rewriting-technical-prose-naturally/examples/에 있다. 인용은 그 파일에서 그대로
옮긴 것이다.
먼저 — 여섯 편이 고르게 쓰지 않는다
세어 보면 이렇다.
| 1인칭 | 그때 든 생각 | 예상이 빗나감 | 독자에게 말 걸기 | 모순·자조 | 겸양 닫기 | |
|---|---|---|---|---|---|---|
| 13569 | 12 | 3 | 5 | 3 | 5 | 1 |
| 17386 | 10 | 5 | 0 | 2 | 1 | 0 |
| 7835 | 8 | 0 | 0 | 3 | 0 | 0 |
| 20161 | 5 | 0 | 0 | 2 | 0 | 0 |
| 22396 | 4 | 0 | 0 | 2 | 0 | 4 |
| 23625 | 1 | 0 | 0 | 0 | 0 | 0 |
13569 한 편에 몰려 있다. 23625는 거의 쓰지 않는데도 읽힌다. 그러니까 이것은 채워야 할 칸이 아니라, 자료가 그런 글일 때만 나오는 것이다.
13569이 그렇게 쓸 수 있었던 이유는 그 글이 「예상보다 빨라져서 문제가 생겼다」는 사건을 실제로 겪었기 때문이다. 겪지 않은 글이 같은 어조를 쓰면 그때부터 거짓이 된다.
1. 고른 이유를 견준 대상과 함께 적는다
무엇을 골랐다가 아니라, 무엇을 놓고 무엇을 골랐고 무엇을 감수했나를 적는다.
22396은 상용 내비게이션을 쓰지 않은 이유를 돈으로 적는다.
하지만 초당 2만 건에 달하는 경로 계산을 위해 API 호출마다 비용이 발생하는 상용 내비게이션을 사용하는 것은 현실적으로 어렵습니다. 게다가 배차를 추천받은 라이더분이 바로 수락하는 경우, 한 번 계산한 거리를 오랜 시간 재활용하기도 쉽지 않습니다.
그리고 고르지 않은 쪽을 표로 남긴다 — TTL 삭제 대 명시적 삭제. 장점 칸이 채워진 쪽을 버리고 단점이 하나뿐인 쪽을 골랐다는 것이 표에 그대로 보인다.
7835는 저장소를 고르는 대목에서 반대 의견을 먼저 적는다.
이벤트는 작은 단위로 저장이 되고, 고속 처리되어야하기 때문에 RDBMS 가 아닌 다른 데이터베이스를 선택해야한다고 생각할 수 있습니다.
그리고 왜 그럼에도 RDBMS인지로 이어 간다.
한다체로 옮길 때 — 어미만 바꾸면 된다. 「~하는 것은 현실적으로 어렵다」·「~라고 생각할 수 있다」.
쓸 수 없는 경우 — 자료에 대안이 없으면 이 항목은 건너뛴다. 「여러 방법을 검토했다」는 검토한 기록이 없으면 지어낸 문장이다.
2. 확인하지 못한 것을 그 대목에서 말한다
이 저장소의 기록은 확인하지 못한 것을 끝에 목록으로 모아 둔다. 참고 글은 그 말이 걸리는 자리
에서 한다.
22396은 압축을 시도한 절 안에서 바로 닫는다.
압축률이 높더라도 원본 데이터가 워낙 커서 압축만으로는 대역폭 문제를 해결할 수 없었습니다.
13569은 배포 전 검토 항목을 늘어놓은 뒤 그 자리에서 한계를 인정한다.
문제가 없을 것으로 예상하였지만 일들이 항상 마음처럼 굴러가던가요?
한다체로 옮길 때 — 끝의 목록을 지우라는 말이 아니다. 목록은 두고, 그중 하나를 그 주장이 나오는 문단 뒤에 한 번 더 놓는다. 읽는 사람이 그 주장을 믿을지 정하는 자리가 거기이기 때문이다.
전 (본문 끝) ## 확인하지 못한 것
role 전달은 확인하지 않았다.
후 (그 대목) 지금 edge 응답은 사용자와 이메일만 전달한다. role을 넘기면 무엇이 달라지는지는
확인하지 않았다.
(본문 끝) ## 확인하지 못한 것 ← 목록은 그대로 둔다
3. 어긋난 자리를 남긴다
자료에 있을 때만 쓴다. 없으면 이 항목은 통째로 건너뛴다.
13569의 「빨라도 문제」 절 전체가 이것이다.
근데 이거 빨라도 너무 빨라진 것 같습니다. '내가 뭘 놓친 게 있나?' 아니면 '코드를 잘못 짰나?' 생각이 들었지만…
그리고 배포 뒤 실제로 문제가 났고, 그 대응이 스스로 모순임을 적는다.
근본적으로는 실행 속도가 너무 빨라진 것이 문제이기 때문에 모순적이지만 우선 단기적인 대응 방안으로 의도적으로 지연 시간을 설정해 천천히 실행하도록 수정하였습니다.
22396은 실패한 시도를 지우지 않는다 — 「시도 1. 데이터 압축」이 실패한 채로 남아 있고, 24MB → 3MB 라는 성공한 압축률까지 적은 다음 그것으로도 모자란다고 닫는다.
한다체로 옮길 때 — 감탄사와 혼잣말은 옮기지 않는다. 옮기는 것은 순서다. 그때 그렇게 생각했다 → 실제로는 이랬다 → 그래서 이렇게 했다.
지어낸 것 놀랍게도 응답은 200이었다.
있는 것 세션 자체는 유효하므로 이 요청이 200으로 처리되는 것은 정상이고, 그래서 이 테스트의
판정 기준은 상태 코드가 아니다.
두 번째는 읽는 사람이 200을 보고 「뚫렸다」고 짐작할 것을 알고 쓴 문장이다. 감정을 적지 않고도 사람이 보인다.
4. 남의 말을 그대로 옮긴다
여섯 편이 가장 자주 쓰는 방법이고, 증거로 뒷받침되므로 지어낼 수 없다.
13569은 최적화를 말하다 말고 격언 셋을 통째로 옮긴다.
"우리는 최적화에 대해서 다음 두가지 규칙을 따른다. 첫째. 하지 마라. 둘째. (전문가 한정) 아직은 하지 마라." M. A. Jackson (1975)
23625는 사용자 문의를 그대로 옮긴다.
심각한 문제는 사용자가 "같은 엑셀 파일을 여러 번 받았다"는 문의였습니다.
20161은 Nginx 문서와 Lucene 문서를 원문 그대로 인용문으로 넣는다.
이 저장소에서 쓸 수 있는 것 — javadoc이 가장 많다. 코드를 쓴 사람이 자기 코드의 위험을 적어 둔 자리가 있으면 그것을 요약하지 말고 그대로 옮긴다.
InboxCleanupJob의 javadoc이 스스로 적는다 — "A single unbounded DELETE over a table that has been accumulating for weeks holds locks long enough to block the very reservations the inbox exists to serve, so the cleanup would cause the outage it is meant to prevent."
이 한 줄이 있으면 「이 결함은 알려져 있었다」는 말을 따로 할 필요가 없다.
5. 한 번은 독자 쪽을 본다
읽는 사람이 틀리게 짐작할 자리에서 한 문장이다. 인사가 아니다.
20161은 겉보기에 멀쩡한 쿼리를 보여 주고 나서 짚는다.
겉으로 보기에는 문제가 없어 보이는 쿼리였지만, 카테고리 필터가 있을 때와 없을 때 검색 API의 응답 속도 차이는 매우 큰 편이었습니다.
22396은 강조를 두 번 한다고 말하고 두 번 한다.
앞서 언급했지만 중요한 내용이기에 다시 한번 강조드립니다. 배달료 책정이나 배민커넥트 앱상에서 활용되는 거리 계산에는 상용 내비게이션이 사용됩니다.
17386은 글 첫머리에 「누가 읽으면 좋을까」를 두고 전제 지식을 못 박는다.
한다체로 옮길 때 — 「~라고 생각하기 쉽다」·「겉보기에는 ~이지만」·「여기서 확인할 값은 ~가 아니다」. 한 기록에 한 번이다. 두 번 넘으면 독자를 끌고 다니는 글이 된다.
옮기지 않는 것 — 「도움이 되길 바랍니다」·「공유드립니다」·「즐거움을 느끼고 있습니다」. 블로그 글의 맺음말 자리에 있는 인사이고, 기록에는 그 자리가 없다.