doc-writinglisted

# 문서 작성 문서·발표자료의 **산문**을 쓰거나 고칠 때 적용한다. 앞으로 모든 저장소의 기준이다. 저장소별 템플릿·해상도·CSS 같은 구체값은 그 저장소 규칙에 두고, 여기에는 옮겨지는 원칙만 적는다. ## 사람이 쓴 글로 AI 티를 뺀다(패턴 전수는 `humanize-korean` 스킬). - **전각 대시(—)로 두 문장을 잇지 않는다.** 접속사나 마침표로 푼다. - **상자·문단마다 첫 문장을 굵히지 않는다.** 굵기는 그 안에서 진짜 중요한 한 곳에만. - **「A가 아니라 B」·「~기 때문입니다」 같은 틀을 연달아 쓰지 않는다.** 단정+부연의 균일한 리듬을 깬다. - 비유·의인화·극적 수사 금지, 도메인 명사에 상태 동사 붙여 줄이지 않기(아래 「기술 사실을 비유로 쓰지 않는다」). - **빼기만 하고 넣지 않는다** — 원문에 없던 상투구를 새로 만들지 않는다. - **연결어미(~하고·~지만·~는데·~면서) 뒤에 쉼표를 찍지 않는다.** 나열 쉼표(A도, B도)는 예외다. ## 기술 사실을 비유로 쓰지 않는다 압축된 비유는 쓴 사람에게만 선명하다. 기준은 하나다 — 읽는 사람이 한 번에 이해하는가. `humanize-korean` 이 안 잡는 축이라 문서 규칙으로 둔다. | 쓰지 않는다 | 이렇게 쓴다 | |---|---| | 대가 | 영향 · 트레이드오프 | | 막다른 분기 | 한 번 실패하면 다시 진행되지 않는 곳 | | `X` 가 갖는다 · `X` 가 준다 | `X` 에 있다 · `X` 에 적혀 있다 | | 인덱스가 이 조회를 받는다 | `(a, b, c)` 인덱스를 쓴다 | | 서로 안 막는다 | 하나가 실패해도 나머지는 그대로 진행된다 | | 유일한 문 · 유일한 자리 · 필요한 전부 | 여기서만 · 하나뿐 · 필요한 값이 다 들어 있다 | | 죽는다 | 실패한다 | | 조용히 낡는다 | 갱신되지 않은 채로 남는다 | | jOOQ 로 간다 | jOOQ 를 쓴다 | 그 분야에서 통용되는 비유(큐·잠금·트��·상속)는 대상이 아니다. **그 분야 밖에서 끌어온 비유**만 걷는다. **도메인 명사에 상태 동사를 붙여 줄이지 않는다.** 멈추는 것은 그 명사가 아니라 **그 명사에 일어나야 할 일**이다 — 「그 요청이 멈춘다」가 아니라 「그 요청은 처리되지 않는다」. **은유를 은유로 바꾸지 않는다.** 「막다른 분기」를 「한 번 걸리면」으로 바꾸는 것은 나아진 것이 아니다 — 뭐가 걸리는지 여전히 안 적혀 있다. 원인은 **실패**다. ## 밀도를 형식에 맞춘다 AI 티를 빼려다 **서술형으로 길어지지 않게.** - 대시를 없앤 자리는 **짧은 마침표 문장**으로 끊는다. 서술형 연결어(~노릇을 한다·~인 것이지·~해 보고서야 알게 된)로 늘리지 않는다. - 슬라이드·표·카드처럼 공간이 정해진 곳은 문장이 아니라 요점. 한 상자 한 요점, 형식명사(것·경우·부분) 줄이기. **명사 종결은 라벨 칸(제목·분류·상태·수치)에만.** 설명·결정·내용 칸은 주어와 동사가 있는 문장이고, 문장이