Documentation Style Guide

문서 작성 가이드

이 문서는 한국기술교육대학교 오픈소스포털 인수인계/운영 문서를 작성할 때의 프로젝트 표준입니다.

1) 목적

• 문서 품질의 편차를 줄이고, 인수인계 속도를 높입니다.
• Wiki(주 문서)와 docs/(미러)를 같은 품질 기준으로 유지합니다.

2) 문서 타입 분류 (프로젝트 표준)

문서는 다음 4가지 타입으로 분류해 작성합니다.

타입	목적	예시 문서
Tutorial	처음부터 따라 하며 성공 경험 제공	onboarding.md 일부
How-to	특정 목표를 달성하는 절차 제공	deploy-ops.md, troubleshooting.md
Reference	빠른 조회 중심의 사실/명세	routing-map.md, api-map.md, config-env.md
Explanation	배경과 설계 의도 설명	architecture.md, project-structure-conventions.md

원칙:

• 하나의 페이지에는 한 타입을 우선 적용합니다.
• 여러 타입이 섞이면 문서를 분리합니다.

3) 페이지 기본 템플릿

문서 타입과 관계없이 아래 순서를 기본으로 사용합니다.

1. 목적/대상
2. 전제 조건
3. 핵심 절차 또는 핵심 구조
4. 예외/실패 케이스
5. 점검 체크리스트
6. 관련 문서 링크

4) 문체/표현 규칙

• 가능한 한 현재형으로 작성합니다.
• 능동태를 우선 사용합니다.
• 독자를 you에 해당하는 직접 대상(예: "담당자", "개발자", "운영자")으로 씁니다.
• 과도하게 쉬움을 암시하는 표현(쉽게, 그냥, 간단히)을 피합니다.
• 비권장 표현 대신 행동 지시를 씁니다.
  • 비권장: "이렇게 하면 안 됩니다."
  • 권장: "Link 컴포넌트를 사용합니다."

5) 포맷 규칙

• 파일/경로/명령어/변수명은 백틱(``)으로 감쌉니다.
• 절차는 번호 목록(1. 2. 3.)으로 씁니다.
• 코드 블록은 언어 태그를 붙입니다.
• 표는 "비교" 또는 "요약" 목적일 때만 사용합니다.
• 스크린샷 의존 설명보다 텍스트 절차를 우선합니다.

6) 사실성 규칙

• 라우트/경로/함수명/환경변수명은 코드 기준으로 검증 후 기록합니다.
• 추측성 문장(아마, 대충)을 금지합니다.
• 운영 절차 문서는 실패 시 복구 경로(롤백/재시도)를 반드시 포함합니다.

7) Wiki + docs/ 동기화 규칙

1. Wiki 페이지를 먼저 수정합니다.
2. 대응되는 docs/*.md를 같은 내용으로 반영합니다.
3. PR 본문에 갱신 문서 경로를 기록합니다.

자세한 운영 규칙은 wiki-sync.md를 따릅니다.

8) 문서 품질 게이트 (PR 전)

• 문서 타입(Tutorial/How-to/Reference/Explanation)이 명확한가?
• 문장 톤(현재형/능동태/직접 지시)이 일관적인가?
• 코드 경로/라우트/변수명이 실제 코드와 일치하는가?
• 절차형 문서에 실패 케이스와 복구 방법이 있는가?
• Wiki와 docs/가 동시에 반영되었는가?

9) 이 프로젝트에서 바로 적용할 우선순위

1. 구조/규칙 변경 시 project-structure-conventions.md 동시 갱신
2. 라우트/API 변경 시 routing-map.md, api-map.md 동시 갱신
3. 인증/권한 변경 시 auth.md 동시 갱신
4. 배포/장애 대응 변경 시 deploy-ops.md, troubleshooting.md 동시 갱신