기술 문서 리뷰

Markdown 포맷

• 목록 — 중첩 목록 포함 모든 목록에 하이픈(-)을 사용한다
• 이미지 — ![이미지설명](path/to/image.png "이미지설명") 형식을 따른다. alt 텍스트가 없으면 확장자를 제외한 파일명을 사용한다
• 코드 블록 — 코드 블록 앞에 반드시 빈 줄을 추가한다. 언어 식별자(bash, hcl, yaml, text 등)를 포함한다
• 들여쓰기 — 모든 코드에 2칸 공백을 사용한다. 언어 자체 관례가 있으면(예: Python은 4칸) 그 관례를 따른다

포맷 과용

• 포맷 요소를 과도하게 사용하면 오히려 가독성이 낮아진다
• 헤더, 굵은 글씨, 백틱으로 가득한 문서는 시각적으로 복잡해지고, 독자는 무엇이 중요한지 파악할 수 없다

헤더 과용:

• 1~2 문장짜리 짧은 내용은 별도 헤더 없이 상위 섹션 아래에 둔다
• 같은 레벨의 헤더가 5개 이상 연속이면 구조를 재검토한다 — 병합하거나 목록으로 대체
• H4 이상(####, #####)은 굵은 글씨나 목록으로 평탄화한다 — 깊은 중첩은 구조 재정비 신호다

굵은 글씨 과용:

• 섹션당 가장 중요한 1~2개의 문장/키워드만 굵게 표시한다
• 목록 항목에서는 핵심 키워드만 굵게 표시한다
• 모든 것이 굵으면 아무것도 강조되지 않는다 — 적을수록 좋다

백틱 과용:

• 백틱은 기술 요소에 사용한다 — 명령어, 파일명, 리소스 이름, 설정 키
• 기술 요소에는 백틱, 강조에는 굵은 글씨를 사용한다
• 한 문장에 백틱이 3개 이상이면 모두 진짜 기술 요소인지 확인한다

자율 판단 기준

• 명시적 규칙이 없는 상황에서는 아래 우선순위로 결정한다:
  1. 업계 표준 — 공식 문서, RFC, 주요 프로젝트 관례를 따른다
  2. 일관성 — 같은 개념은 문서 전체에서 같은 표기를 사용한다
  3. 독자 이해 — 한국어가 더 명확하면 한국어, 영어가 표준 용어면 영어를 사용한다
• 고유명사(제품/프로젝트 이름) — 원래 언어와 정확한 표기를 유지한다
• 일반 개념 — 맥락에 따라 한국어 또는 영어를 선택한다
• 약어 — 첫 등장 시 풀어서 설명한다

검토 순서

아래 순서로 검토한다:

1. 맞춤법 및 문법
2. 문장 구조와 가독성
3. 용어 일관성 (규칙 + 자율 판단)
4. Markdown 포맷 (목록, 이미지, 코드 블록, 들여쓰기)
5. 포맷 과용 (헤더, 굵은 글씨, 백틱)
6. 최종 확인: 입문자도 이해할 수 있는가?

변경 사항 보고

• 아래 변경 사항은 반드시 사용자에게 보고한다:
  • 삭제한 문장이나 문단
  • 의미가 바뀐 재작성
  • 주요 용어 변경
  • 구조 재편
  • 목록에 없는 용어 통일 결정 (예: "docker → Docker로 공식 브랜딩에 맞게 통일")

품질 체크리스트

• 명확성: 기술 용어를 첫 등장 시 설명한다
• 일관성: 같은 개념, 같은 표기
• 정확성: 기술적 오류 발견 시 표시한다
• 접근성: 입문자도 따라갈 수 있다
• 자율성: 규칙에 없는 내용은 맥락과 독자를 고려해 최선의 판단을 내린다

예시

대소문자 혼용:

"Prometheus", "prometheus", "PROMETHEUS" 혼용
→ Prometheus로 통일 (공식 프로젝트 표기)
→ 보고: "Prometheus 대소문자를 공식 표기법으로 통일했습니다"

한국어/영어 혼용:

"컨테이너"와 "container" 혼용
→ 일반 설명: 컨테이너 (독자 친화적)
→ 기술 명령어/리소스 맥락: container (정확성)
→ 보고: "컨테이너/container를 맥락별로 구분하여 사용했습니다"

트렌드 용어:

"서버리스"와 "serverless" 혼용
→ 서버리스로 통일 (한국 개발자 커뮤니티 통용 표현)
→ 보고: "서버리스로 통일 (업계 통용 표현)"