한국어 기술 문서 스타일 가이드
어조
문서 유형별 권장 어조
| 유형 | 권장 어조 | 예시 |
|---|---|---|
| 가이드 / 튜토리얼 | 존댓말 | "먼저 환경 변수를 설정합니다." |
| 레퍼런스 / 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가 발생하는 경우" 같은 가정형 적극 사용
피해야 할 표현
| 피해야 할 표현 | 대체 |
|---|---|
| "쉽게 ~할 수 있습니다" | "다음 명령으로 ~합니다" (난이도 판단은 독자에게) |
| "당연히 ~" | 전제를 명시 |
| "단순히 ~" | 평가어 제거 |
| "~인 것 같습니다" (레퍼런스에서) | 단정 또는 측정값 인용 |
등급 기준
문체 일관성 (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점: 톤이 문서 목적을 방해함