본문으로 건너뛰기

문서 명확성 원칙

핵심 원칙​

기술 문서의 목적은 독자가 작업을 끝내게 하는 것이다. 멋진 문장이 아니라 빠르게 막힘 없이 닿는 문장이 좋은 문장이다.

구조 판단 기준​

헤딩 위계​

  • H1은 문서당 1개 — 문서의 정체성
  • H2는 큰 주제 단위 — 독자가 목차로 훑었을 때 길을 잡는 곳
  • H3 이하는 H2의 하위 분류일 때만 사용
  • 헤딩만 읽어도 문서의 줄거리가 나와야 한다

섹션 도입부​

각 H2 섹션의 첫 문장은 다음 중 하나여야 한다:

  • 해당 섹션이 답하는 질문
  • 해당 섹션의 핵심 주장
  • 독자가 이 섹션에서 얻을 결과

도입부가 "다음으로는 ~를 설명한다"로 시작하면 약하다.

명확성 판단 기준​

한 번에 닿는가​

좋은 문단의 조건:

  • 한 문단은 한 가지 생각을 다룬다
  • 5문장을 넘기지 않는다
  • 첫 문장이 문단의 결론이다 (BLUF: Bottom Line Up Front)

전제 친절도​

다음 패턴이 발견되면 전제가 부족하다:

  • 약어가 정의 없이 처음 등장
  • 외부 도구/개념이 설명 없이 인용됨
  • "당연히 ~ 했을 것이다"는 식의 가정

등급 기준​

명확성 (A/B/C/D)​

등급기준
A첫 독자가 한 번에 통과
B1~2곳에서 멈칫하나 회복 가능
C핵심 섹션에서 막힘이 반복됨
D요지를 추출할 수 없음

구조 (A/B/C/D)​

등급기준
A헤딩만으로 줄거리 파악 가능
B헤딩 흐름이 대체로 자연스러움
C헤딩 위계가 임의적
D같은 레벨에 이질적 주제가 섞임

독자 친화성 (1~5점)​

  • 5점: 전제, 호흡, 결론이 모두 갖춰진 문서
  • 3점: 약점 있으나 따라갈 수 있음
  • 1점: 사전 지식 없이 따라가기 불가능

위 세 축은 "숙련 독자가 한 번에 닿는가"를 본다. **"AI 입문자가 이전 편 없이 이탈하지 않는가"**는 별도 렌즈로 본다 — [[reader-centered-voice]] §2 (은유 자족성·핵심 개념 조기 정의·미정의 전문어 밀도·회수 밀도·건너뛰기 안내·"쉽게 말해"), 척도는 입문자 통과율 1~5.

자주 보이는 패턴​

패턴권장
"~할 수 있습니다" 남용단정형 능동태로
한 문장에 쉼표 4개 이상분할
"이것/그것/저것" 지시어 연쇄구체 명사 반복
결론 없이 끝나는 섹션한 줄 정리 추가