문서 유형별 권장 어조
| 유형 | 권장 어조 | 예시 |
|---|
| 가이드 / 튜토리얼 | 존댓말 | "먼저 환경 변수를 설정합니다." |
| 레퍼런스 / API 문서 | 평어 | "이 함수는 X를 반환한다." |
| 릴리스 노트 | 평어 | "v2.0에서 X가 추가됨." |
| README | 존댓말 또는 평어 (1개만) | — |
어떤 어조든 한 문서 안에서는 통일한다.
어조 혼용 검출 패턴
- "~합니다" 와 "~한다"가 같은 섹션에 등장
- 한 문단 안에서 종결어미가 바뀜
- 명령형(~하세요)과 서술형(~한다)의 혼재
표기 규칙
영문 단어
| 종류 | 표기 |
|---|
| 약어 | 모두 대문자 (API, URL, JSON) |
| 제품/서비스명 | 원문 대소문자 보존 (GitHub, npm, Node.js) |
| 일반 기술 용어 | 소문자 (cache, queue) — 단, 한글 번역어 우선 |
숫자와 단위
- 숫자와 단위 사이는 반각 공백 —
5 GB, 200 ms, 10 MB/s
- 퍼센트는 붙임 —
95%
- 시간 표기는 ISO 8601 권장 —
2026-05-25T04:00:00Z
따옴표와 괄호
- 코드/명령은 백틱:
npm install
- 인용/강조는 큰따옴표: "이렇게"
- 부연은 둥근괄호 (...)
- 선택지는 대괄호 [optional]
- 변수는 꺾쇠괄호
<placeholder> 또는 중괄호 {var} — 한 문서에서 하나만
톤 매칭
문서 유형별 톤
- 가이드/튜토리얼: 격려하고 안내하는 톤 — 독자가 따라할 수 있다는 신호
- 레퍼런스: 사실 진술, 감정/평가 배제
- 트러블슈팅: 공감하는 톤, "X가 발생하는 경우" 같은 가정형 적극 사용
피해야 할 표현
| 피해야 할 표현 | 대체 |
|---|
| "쉽게 ~할 수 있습니다" | "다음 명령으로 ~합니다" (난이도 판단은 독자에게) |
| "당연히 ~" | 전제를 명시 |
| "단순히 ~" | 평가어 제거 |
| "~인 것 같습니다" (레퍼런스에서) | 단정 또는 측정값 인용 |
사람 목소리 (Human Voice) — AI 정돈 문체 걷어내기
사람이 직접 경험을 떠올리며 쓴 글처럼. 원문의 개성과 말투를 유지하면서, 지나치게 정돈된 AI 문체·교과서식 설명·뻔한 접속어·과도한 소제목과 목록을 피한다. 경험과 생각이 자연스럽게 이어지는 흐름을 살리고, 조금 거칠더라도 필자의 온도를 남긴다. (사용자 기준, 2026-09-07)
열 가지 기준
- 사람이 직접 경험을 떠올리며 쓴 글처럼 쓴다
- 지나치게 완벽하게 정리하거나 모든 내용을 항목화하지 않는다
- 문장 길이와 호흡을 일정하게 맞추지 않는다 — 짧은 문장과 긴 문장을 섞는다
- 교과서식 정의보다 실제 상황, 판단, 의문, 시행착오를 중심으로 푼다
- 결론을 먼저 정해 놓고 설명하지 않는다 — 생각이 이어지는 흐름을 살린다
- '핵심은', '즉', '결론적으로', '~를 넘어', '단순히 ~가 아니라' 같은 전형적 AI 표현을 반복하지 않는다
- 불필요한 소제목, 요약, 번호 목록, 과도한 강조를 쓰지 않는다
- 원문의 말투와 개성을 유지하되, 의미가 불분명하거나 호흡이 끊기는 부분만 다듬는다
- 맞춤법은 바로잡되 지나치게 매끈하게 만들지 않는다 — 필자의 온도와 약간의 거친 느낌을 남긴다
- 가르치거나 설득하는 매뉴얼 문체보다, 경험을 공유하며 함께 생각하는 어조를 쓴다
검출 패턴 (style-enforcer 가 센다)
| 패턴 | 신호 | 20편 v1.22.5 실측 → 다듬은 뒤 |
|---|
| "A가/이 아니라 B" 대구 | 편당 10회 넘으면 AI 정돈 냄새 | 29 → 8 안팎 |
| 줄표(—)로 문장 잇기 | 문단마다 2개 넘으면 호흡이 같아진다 — 쉼표·마침표로 끊기 | 183 → 60 안팎(이미지 alt·표 제외) |
**굵게** | 편당 20곳 넘으면 강조가 강조가 아니다 | 120 → 10 안팎 |
| 첫째·둘째·셋째 / 번호 목록으로 생각 정리 | 데이터가 아닌 '생각'을 목록화하면 교과서 | 8 → 0 |
| 문두 "그리고" 연쇄 | 문장을 잇지 말고 끊는다 | 17 → 절반 |
| 의문·시행착오 부재 | "처음엔 … 싶었다", "여기서 좀 헤맸다"류 한 편에 두어 군데는 있어야 사람 글 | 0 → 3 |
표(데이터)와 코드 블록은 이 기준의 대상이 아니다. 3줄 요약·낱말 박스처럼 시리즈 규약이 정한 목록도 예외.
- "A가 아니라 B" → B만 말하거나, "A인 줄 알았는데 B였다"처럼 시간 순으로
- 줄표 → 마침표로 끊고 다음 문장으로. 정말 삽입이 필요할 때만 쉼표
- 굵게 → 한 절에 하나 이하. 나머지는 문장 자체로 힘을 내게
- 첫째·둘째 → "우선 … 는 것. … 도 재미있다. 그리고 …" 식의 흐름
- 판정을 내리기 전에 "솔직히 당황했다", "나빠진 건가" 같은 필자의 첫 반응을 한 줄
등급 기준
문체 일관성 (A/B/C/D)
| 등급 | 기준 |
|---|
| A | 어조/시점이 완벽히 통일 |
| B | 1~2곳 혼용, 의미 전달엔 무리 없음 |
| C | 섹션 단위로 어조가 흔들림 |
| D | 한 문단 안에서도 혼용 |
표기 정확도 (A/B/C/D)
| 등급 | 기준 |
|---|
| A | 표기 규칙 100% 준수 |
| B | 90% 이상 |
| C | 70% 이상 |
| D | 핵심 표기가 임의적 |
톤 매칭 (1~5점)
- 5점: 문서 유형에 정확히 부합하는 톤
- 3점: 톤은 일관되나 문서 유형과 약간 어긋남
- 1점: 톤이 문서 목적을 방해함