문서 명확성 원칙

핵심 원칙

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

구조 판단 기준

헤딩 위계

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

섹션 도입부

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

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

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

명확성 판단 기준

한 번에 닿는가

좋은 문단의 조건:

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

전제 친절도

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

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

등급 기준

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

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

구조 (A/B/C/D)

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

독자 친화성 (1~5점)

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

자주 보이는 패턴

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