diff --git a/docs/ko-writing-style-guide.md b/docs/ko-writing-style-guide.md new file mode 100644 index 000000000..37c66188e --- /dev/null +++ b/docs/ko-writing-style-guide.md @@ -0,0 +1,84 @@ +# 한국어 문서 표현 가이드 (교정/교열) + +이 문서는 `jk/proofread-ko-source` 브랜치의 교정 내용을 취합해, QueryPie 한국어 문서에서 자주 발생하는 표현 오류와 권장 표현을 정리한 기준서입니다. + +## 문서 이름 + +- 권장 파일명: `ko-writing-style-guide.md` +- 이유: 한국어(`ko`) + 문장 표현(`writing style`) + 가이드(`guide`)를 직관적으로 드러내며, `docs/`의 기존 영문 파일명 규칙과도 일관됩니다. + +## 적용 범위 + +- 대상: `src/content/ko/**/*.mdx` +- 목적: 의미를 바꾸지 않으면서 가독성, 정확성, 일관성을 높이는 교정 + +## 핵심 원칙 + +1. 장황한 피동/명사형 표현보다 능동형 서술을 우선합니다. +2. 띄어쓰기(합성어, 의존 명사, 조사 결합)를 표준 표기로 맞춥니다. +3. 제품/기능명, UI 라벨, 기술 용어의 표기 일관성을 유지합니다. +4. 사용자 안내 문장은 정중하고 간결한 톤으로 통일합니다. + +## 원칙별 이유와 근거 + +1. 장황한 피동/명사형 표현보다 능동형 서술을 우선합니다. +- 이유: 사용자가 해야 할 동작이 더 직접적으로 드러나고 문장 길이가 짧아집니다. +- 근거: `~이 가능합니다`를 `~할 수 있습니다`로 바꾼 교정이 대량으로 반복되었고, 같은 의미를 더 명확하게 전달했습니다. + +2. 띄어쓰기(합성어, 의존 명사, 조사 결합)를 표준 표기로 맞춥니다. +- 이유: 띄어쓰기 오류는 의미 해석을 방해하고 문서 신뢰도를 떨어뜨립니다. +- 근거: `민감정보`, `상세페이지`, `Key 를` 같은 패턴이 반복 수정되었고, 표준 띄어쓰기로 정리할 때 문장 일관성이 높아졌습니다. + +3. 제품/기능명, UI 라벨, 기술 용어의 표기 일관성을 유지합니다. +- 이유: 같은 대상을 여러 이름으로 부르면 독자가 다른 개념으로 오해할 수 있습니다. +- 근거: `커버로스 -> Kerberos`, `Internal -> Interval`처럼 용어 정확도 교정이 다수 발생했고, UI/기술 문서에서 정확 표기가 직접적인 기능 이해에 영향을 줍니다. + +4. 사용자 안내 문장은 정중하고 간결한 톤으로 통일합니다. +- 이유: 고객 문서는 친절하지만 단정한 톤이 필요하며, 과도한 구어체/명령형은 피해야 합니다. +- 근거: `참고해주세요`를 `참고해 주세요` 또는 `참고하시기 바랍니다`로 교정한 사례처럼, 존중 표현과 톤 일관성 확보가 반복적으로 필요했습니다. + +## 자주 틀리는 유형과 권장 표현 + +| 유형 | 잘못된 표현 | 권장 표현 | 틀린 이유 | 올바른 표현 근거 | +|---|---|---|---|---| +| 가능 표현 남용 | 검색이 가능합니다. | 검색할 수 있습니다. | 명사형+서술어 결합으로 문장이 길고 동작성이 약함 | 사용자 행동 중심 문장으로 전환해 이해 속도 향상 | +| 명사형 과다 | 정보 조회가 가능합니다. | 정보를 조회할 수 있습니다. | 행위 주체/대상이 흐려짐 | 목적어+동사 구조로 의미가 분명해짐 | +| 조사/어미 결합 | 클릭하여 | 클릭해 | 안내 문장에서 불필요하게 딱딱함 | 절차형 UI 문서에서 간결한 연결 어미가 가독성에 유리 | +| 불필요 쉼표 | 경우, / 시, / 후, | 경우 / 시 / 후 | 조사 뒤 쉼표 남용으로 호흡이 끊김 | 의미 구분이 필요할 때만 쉼표 사용 | +| 합성어 띄어쓰기 | 민감정보 / 민감데이터 | 민감 정보 / 민감 데이터 | 붙여쓰기로 단어 경계가 불명확함 | 일반 명사 결합은 띄어써 의미 단위를 분명히 함 | +| 의존 명사 | 내의 | 내 | 불필요한 표현 중복 | 더 짧고 자연스러운 표준 문장 구성 | +| 조사 분리 오류 | Key 를 | Key를 | 체언+조사를 띄어 씀 | 조사 결합 원칙에 따라 붙여 씀 | +| 구어체/모호 표현 | 참고해주세요. | 참고해 주세요. / 참고하시기 바랍니다. | 구어체에 가까워 공식 문서 톤과 불일치 | 고객 문서의 정중한 안내 톤 유지 | +| 어색한 조사 | 통해서 | 통해 | 문장이 늘어지고 중복 느낌 | 의미 동일 시 더 간결한 형태 우선 | +| 오탈자/용어 | 커버로스 | Kerberos | 기술 용어 오기 | 표준 기술 명칭 원문 유지 | +| 오탈자 | Internal | Interval | 의미가 다른 단어로 오기 | UI/설정값은 정확 표기가 기능 이해의 전제 | +| 띄어쓰기 | 상세페이지 / 디테일페이지 | 상세 페이지 / 디테일 페이지 | 복합 명사를 임의로 붙여 씀 | 일반 문서 표기에서는 띄어쓰기로 가독성 확보 | + +## 표현 통일 가이드 + +1. 안내 문구 +- 기본: `~할 수 있습니다.` +- 주의/권고: `~유의하시기 바랍니다.`, `~참고하시기 바랍니다.` + +2. 작업 절차 문장 +- `~버튼을 클릭해 저장합니다.` +- `~항목에서 값을 선택합니다.` + +3. UI/기술 용어 +- 제품/기술 고유명은 원문 표기를 유지합니다. 예: `Kerberos`, `Workflow`, `MongoDB` +- 동일 문서 내에서 한 번 정한 표기(예: `정책 예외`)를 끝까지 유지합니다. + +## 최소 점검 체크리스트 + +1. `~이 가능합니다`를 `~할 수 있습니다`로 바꿔도 의미가 유지되는가? +2. `민감정보`, `정책예외`, `상세페이지` 같은 붙여 쓰기를 표준 띄어쓰기로 정리했는가? +3. `Key 를`, `+srv 를`처럼 영문 용어 뒤 조사 띄어쓰기가 잘못되지 않았는가? +4. `커버로스`, `Vaule`, `controland` 같은 오탈자를 수정했는가? +5. 같은 개념의 표기가 문서 내에서 혼용되지 않는가? + +## 참고: 브랜치 분석에서 자주 관찰된 교정 패턴 + +- `검색이 가능합니다.` → `검색할 수 있습니다.` (다수) +- `정보 조회가 가능합니다.` → `정보를 조회할 수 있습니다.` (다수) +- `경우,` → `경우` (다수) +- `클릭하여` → `클릭해` (다수)