doc-refine — 기술 문서 읽기 경험 최적화 가이드
검토 및 수정 경계
먼저 검토와 수정을 구분합니다. 검토만 요청된 경우 문제점과 제안을 제공하고, 수정이 명확히 요청된 경우에만 권한이 부여된 문서를 수정합니다. 행동이나 사실의 변화(표현 조정이 아닌)가 관련된 경우, 원래 의도를 유지하고 확인이 필요한 부분을 지적합니다.
축소 전 보호: 기술적 행동, API/데이터 계약, 전제 조건 및 경계 조건, 보안 및 법적 경고, 접근성 대체 설명, 유효한 예제, 출처 링크 및 안정적인 앵커. 코드에 동일한 동작이 존재한다고 해서 문서에서 삭제할 수 있는 충분한 근거가 되지는 않으며, 지역적으로 필요한 반복은 독립적인 읽기를 도울 수 있습니다.
두 가지 검사 목표
모든 판단은 궁극적으로 두 가지 질문으로 귀결됩니다.
| 공리 | 스스로에게 묻는 질문 | 한 마디 |
|---|---|---|
| ① 빠른 탐색 | 대상 독자가 목차와 제목만으로 정보 위치를 판단할 수 있는가? | 이정표가 명확함 |
| ② 각 단락의 목적 | 삭제했을 때 작업 완료, 동작 이해 또는 위험 통제에 필요한 정보가 손실되는가? | 정보가 완전하고 간결함 |
모든 내용에 대해 이 두 가지 검증을 수행합니다. ①을 충족하지 못함 → 제목 수정/다이어그램 추가/구조 조정. ②를 충족하지 못함 → 보호 항목과 독자 작업을 확인한 후 병합 또는 축소 제안; 분량 때문에 필수 내용을 삭제하지 않음.
작업 흐름
1. 진단 (먼저 전체를 읽고, 서두르지 않음)
대상 문서를 처음부터 끝까지 읽고, 섹션별로 문제점을 기록합니다.
- 제목이 번호 없이도 내용을 독립적으로 전달하는가? (아니요 → 공리 ① 위반)
- 동일한 논리/규칙이 2곳 이상에 나타나는가? (예 → 공리 ② 위반)
- 이 동작 설명이 사용자가 계약, 제한 사항 또는 결과를 이해하는 데 도움이 되는가? 먼저 용도를 판단하고, "무엇인지/왜인지"에 따라 기계적으로 삭제하지 않음.
- 안내 문구가 단순한 반복에 불과한가? 표현을 간결하게 할 수 있지만, 단계 위치 지정, 경고 또는 제한 사항은 유지해야 함.
- 3개 이상의 항목 비교가 산문에 흩어져 있는가? (예 → 표를 사용해야 함)
- 그림이 텍스트보다 프로세스나 상태를 이해하기 쉬운가? 대상 렌더러의 기능에 따라 Mermaid를 선택하거나 텍스트를 유지함.
- 예제가 실제 질문, 오류 복구 또는 경계 사례를 해결하는가? 대상 독자에게 효과적인 예제는 유지함.
2. 수정 (공리별로 분류하여 적용)
구체적인 규칙은 아래 §공리 ① 및 §공리 ②를 참조하십시오.
3. 검증 (정량적 기준)
수정 후 필요에 따라 검증 체크리스트를 읽고 정보 완전성과 읽기 효과를 확인합니다. 모든 숫자가 반드시 충족되어야 하는 것은 아닙니다. 이는 진단 도구일 뿐 법률이 아니며, 명확성이 우선시될 때 예외를 둘 수 있습니다.
공리 ①: 빠른 탐색
제목 식별력
제목은 이정표입니다. 유지관리자가 TOC를 훑어볼 때 각 섹션에 무엇이 있는지 한눈에 알 수 있어야 합니다.
판단 기준: 섹션을 클릭해야 내용을 알 수 있다면 제목이 너무 모호한 것입니다.
| ❌ 너무 모호함 | ✅ 식별 가능 | 수정 이유 |
|---|---|---|
5.1 테이블 수준 | 5.1 프로젝트 CRUD (테이블 수준 엔드포인트) | "테이블 수준"은 무엇이든 될 수 있음 |
5.3 행 수준 | 5.3 행 수준 협업 엔드포인트 | 독자가 인수/전달 등의 작업이 있음을 알 수 있음 |
5.4 내보내기 | 5.4 전체 CSV 내보내기 | 어떤 형식? 전체인가 부분인가? |
엔드포인트 | HTTP 엔드포인트 | 모호성 제거 |
팁: 핵심 개념이 너무 짧으면 괄호 안에 한정어를 추가하여 핵심 정보를 보충합니다. 하지만 과용하지 마십시오. 목표는 15자 이내로 "이 섹션에 무엇이 있는지" 전달하는 것이지, 논문 제목을 작성하는 것이 아닙니다.
정보 구조
- 한 섹션 한 역할: 튜토리얼, 작업, 참조 또는 설명의 주요 독자 작업에 따라 내용을 구성합니다. 필요한 API 서명이나 간단한 배경은 유지할 수 있으며, 긴 자료는 교차 링크를 사용합니다.
- 핵심 먼저, 세부 사항은 나중에: 가장 중요한 정보를 섹션 시작 부분이나 문서 상단에 배치합니다(점진적 공개, Progressive Disclosure). 고급/에지 정보는 접거나 부록에 넣을 수 있습니다.
- 자족 원칙: 유지관리자가 어떤 페이지에서든 읽기 시작할 수 있도록 "선행 지식"이 필요하지 않아야 합니다(Every Page is Page One). 선행 개념이 필요한 경우 섹션 상단에 명시하고 링크를 추가합니다.
다이어그램 대체 텍스트
관계, 순서 또는 비교가 그림으로 더 명확할 때만 그림을 사용합니다. 검색 가능한 텍스트와 필요한 대체 설명은 유지합니다.
의사 결정 트리:
정보 유형은?
├─ 여러 단계 프로세스 / 분기 판단 포함 → 순서도 (flowchart)
├─ 이벤트 기반 상태 변경 → 상태 다이어그램 (stateDiagram-v2)
├─ 3+ 항목 × 2+ 차원 비교 → 표
├─ 구성 요소 관계 / 아키텍처 계층 → 개요도 + 계층
├─ 정의 / 맥락 / 정확한 수치 → 텍스트 (기본값)
└─ 불확실 → 기본 텍스트 (다이어그램은 장식이 아닌 보너스)
Mermaid 모범 사례:
- 노드 ≤30개 — 초과 시 레이아웃 알고리즘을 읽을 수 없으므로 "개요→세부" 여러 다이어그램으로 분할
- 분기 조건과 의미가 불분명한 관계에는 레이블을 추가합니다. 명확한 순서 화살표는 레이블을 생략할 수 있어 레이블 노이즈를 방지합니다.
subgraph를 사용하여 관련 노드를 그룹화합니다.TD(위에서 아래로)는 계층 구조에 적합하고,LR(왼쪽에서 오른쪽)은 시퀀스/파이프라인에 적합합니다.
표 디자인 (Tufte 원칙):
- 불필요한 선, 음영, 순수 장식을 제거합니다. "무엇보다 데이터를 보여주세요"
- 최소한의 효과적인 차이: 시각적 구분은 가능한 미묘하지만 명확해야 합니다.
- 숫자는 열을 기준으로 정렬하여 스캔 및 비교를 용이하게 합니다.
- 텍스트는 항상 수평으로 유지하며, 세로 배치는 금지합니다.
공리 ②: 각 단락의 목적
중복 제거
동일한 정보가 여러 곳에 나타나는 것은 유지보수성의 최대 적입니다. 한 곳을 수정하고 다른 곳을 잊어버리기 때문입니다.
감지 기준 (하나라도 해당 → 중복 제거 필요):
- 동일한 논리/규칙이 2개 이상의 섹션에 나타나는 경우 → 권위 있는 출처(일반적으로 데이터 모델 또는 상태 머신 섹션)를 남기고 나머지는 교차 참조로 변경
- 동작, 전제 조건, 위험 및 독립적 읽기를 확인한 후 정보 손실이 없는 단락 → 병합 또는 축소
- 문서가 구현 세부 사항을 반복하는 경우 → 독자에게 필요한지 판단. 동작 설명과 계약은 유지하고, 코드에 이미 존재한다는 이유로 삭제하지 않음
- 여러 가지 동등한 방법이 있는 경우 → 기본 권장 사항을 제시하고, 호환성, 권한 또는 사용 조건이 다른 필수 대안은 유지
ARID ≠ DRY: 문서는 필요한 반복을 허용합니다. 튜토리얼에서 참조 섹션의 개념을 다시 설명하는 것은 합리적입니다. 그러나 병렬 유지보수를 제거합니다. 동일한 사실을 두 곳에서 독립적으로 유지보수해서는 안 됩니다. 그렇지 않으면 반드시 한 곳이 구식이 됩니다.
간결화
독자의 현재 요구에 기여하지 않는 모든 것을 제거합니다.
| 나쁜 냄새 | 수정 방법 | 이유 |
|---|---|---|
| 반복적인 서두: "이 섹션에서는 ...를 논의하겠습니다" | 직접적인 표현으로 병합 | 필요한 단계 위치 지정은 유지 |
| 채우기 단어: "주의할 점은" / "언급할 가치가 있는 것은" | 안내 문구 간소화 | 경고나 제한 사항 자체는 유지해야 함 |
| 수동태 연발 ("...에 사용됩니다" "...될 것입니다") | 능동 SVO로 변경 | 더 짧고 명확하며 독자가 "누가 무엇을 하는지" 알 수 있음 |
| 동의어 표류 (동일 기능을 다른 단어로 지칭) | 용어 통일, 단어당 하나의 의미 | 독자가 동일 기능의 이름을 명확히 알 수 있도록 함 |
| 읽기 어려운 긴 중첩 문장 | 논리에 따라 문장 분할 | 조건, 예외 및 결과의 관계를 분리하지 않음 |
| 동등한 솔루션 나열 | 권장 솔루션을 먼저 제시하고, 필수 대안은 나중에 | 다른 제약 조건에서 실행 가능한 선택을 유지 |
예제 절제
예제는 가장 강력한 빠른 답변 도구이지만, 가장 남용되기 쉬운 콘텐츠 유형이기도 합니다. Write the Docs는 특히 "(일부) 예제 포함"이라고 명시합니다. 괄호 안의 "일부"는 의도적인 제한입니다.
예제를 사용해야 하는 경우:
- 독자가 빠른 답변을 원하며, 바로 예제로 건너뛸 것입니다 (많은 사람의 첫 반응)
- 구체적인 예가 없으면 개념을 이해하기 어려운 경우
- 고빈도, 실제 사용 사례를 보여주는 경우
예제를 사용하지 말아야 하는 경우:
- 명백한 것을 보여줄 때 (Microsoft: "Don't illustrate obvious points")
- 이해에 도움이 되지 않는 인위적인 시나리오. 명확하게 표시되고 동작을 검증할 수 있는 합성 예제는 유지 가능
- 단지 "완전성"을 위해 추가했으며 사용자 실제 요구에 의해 동기화되지 않은 경우
- 예제가 이미 너무 많음 — 더 추가하면 스캔 가능성이 떨어짐
좋은 예제:
- 가장 일반적인 사용 사례만 다루고, 모든 경우를 열거하지 않음
- 자체 포함되어 실행 가능 (복사하여 붙여넣기만 하면 작동)
- 단순한 것에서 복잡한 것으로 점진적
- 예상 출력을 보여주어 독자가 검증할 수 있도록 함
- 예제가 여전히 실행 가능하거나 전제 조건이 명확한 경우에만 상용구를 생략합니다. 필수 import, 오류 처리 및 예상 출력은 유지합니다.
나쁜 예제:
- 명백한 것을 보여줌
- 비현실적인 인공 시나리오
- 하나의 예제가 너무 많은 변수를 다루려고 함
- 예제와 관련 없는 예외 처리를 포함
- 검증되지 않았지만 실행 가능하다고 주장하는 코드. 실행 불가능한 경우 검증 제한을 명확히 표시해야 함
위치 규칙:
- 간단한 한 줄 예제 → 본문에 인라인으로 포함
- 긴 예제 → 밀집된 참고 자료와 분리 (독립적인 단락 또는 접힌 영역)
- 참조 문서의 예제 → 절제를 유지하고 사용법 설명만 제공하며, 교육과 혼용하지 않음
정량적 기준 빠른 참조
다음은 언어와 독자에 따라 조정된 초기 스크리닝 힌트일 뿐입니다. 자세한 내용은 검증 체크리스트를 참조하십시오.
| 차원 | 제안 시작점 | 사용 경계 |
|---|---|---|
| 영어 문장 길이 | 약 20단어 이후 중첩 주의 | 중국어에 기계적으로 적용하지 말고, 조건과 계약을 깨뜨리지 않음 |
| 단락 | 한 단락에 하나의 주요 아이디어 | 예외와 경고는 원래 단락에 따를 수 있음 |
| 목록/단계 | 긴 경우 그룹화 고려 | 항목 수를 맞추기 위해 완전한 단계를 삭제하지 않음 |
| 수동태 | 주체가 불분명할 때 수정 | 반드시 달성해야 하는 비율을 설정하지 않음 |
| Mermaid | 노드가 많을 때 개요와 세부 사항 고려 | 실제 렌더링 가독성으로 판단 |
| 표 | 넓은 표는 분할 또는 전치 고려 | 비교에 필요한 열과 단위 유지 |
숫자는 제안일 뿐이며, 업계 합격 기준이나 연구 법칙이 아닙니다. 사실, 계약, 안전 또는 법적 텍스트를 변경하기 위해 기준을 충족시키려 하지 마십시오.
안티패턴 빠른 참조
| 안티패턴 | 증상 | 해결 방법 |
|---|---|---|
| Almighty Thud | 거대 문서, 모든 정보가 동등한 가중치를 가지며, 주요 결정이 묻힘 | 분할 또는 우선순위 계층 추가 |
| 유형 혼용 | 튜토리얼에 API 참조를 넣고, 참조에 "왜"를 씀 | Diátaxis에 따라 분리 |
| 반복적인 서두 | 실질적인 정보가 없는 안내 문구 | 표현 간소화, 위험 및 단계 정보 유지 |
| 동의어 표류 | 동일 기능을 다른 단어로 지칭 | 용어 통일 |
| 관계 불명확 | 분기나 화살표의 의미를 추측해야 함 | 불명확한 관계에 레이블 추가 |
| chartjunk | 표에 불필요한 장식선, 음영 추가 | 정보를 전달하지 않는 장식 제거 |
| 예제 과부하 | 모든 시나리오의 예제를 열거 | 가장 일반적인 사용 사례만 유지 |
| 병렬 유지보수 | 동일한 사실을 여러 곳에서 독립적으로 유지보수 | 한 곳만 남기고 나머지는 링크로 변경 |