문서 템플릿 가이드

Kyndof OS 공식 문서 템플릿 모음

개요

이 디렉토리는 Kyndof OS에서 사용하는 표준화된 문서 템플릿을 제공합니다. 일관된 문서 작성을 통해 팀 간 커뮤니케이션과 지식 공유를 개선합니다.

사용 가능한 템플릿

1. 정책 템플릿 (Policy)

파일: _policy.md

용도: 회사 전체 또는 팀 내 정책, 규정, 가이드라인

사용 시점:

새로운 회사 정책 수립 시
보안, 개인정보, 규정 준수 관련 문서
표준 운영 절차 (SOP) 정의 시

예시:

보안 정책
개인정보 처리 방침
코드 리뷰 정책
배포 승인 정책

특징:

YAML frontmatter로 메타데이터 관리
TL;DR 섹션으로 핵심 내용 요약
예외 사항 및 FAQ 포함
검토 주기: 6개월 (biannual)

2. 프로세스 템플릿 (Process)

파일: _process.md

용도: 단계별 업무 프로세스, 워크플로우

사용 시점:

반복적인 업무 절차 문서화
복잡한 멀티스텝 워크플로우
팀 간 협업이 필요한 프로세스

예시:

배포 프로세스
인시던트 대응 프로세스
신규 서비스 런칭 프로세스
데이터 마이그레이션 프로세스

특징:

Mermaid 다이어그램으로 흐름 시각화
단계별 체크리스트 제공
예외 처리 및 문제 해결 섹션
검토 주기: 3개월 (quarterly)

3. How-to 템플릿 (How-to/Runbook)

파일: _how-to.md

용도: 실전 가이드, 작업 매뉴얼, 런북

사용 시점:

특정 작업 수행 방법 설명
기술적 설정 가이드
온보딩 자료
트러블슈팅 가이드

예시:

로컬 개발 환경 설정
데이터베이스 백업 방법
CI/CD 파이프라인 설정
모니터링 대시보드 사용법

특징:

난이도 표시 (beginner/intermediate/advanced)
예상 소요 시간 명시
단계별 명령어 및 예상 결과 제공
문제 해결 섹션 포함
검토 주기: 1개월 (monthly)

4. 개념 템플릿 (Concept)

파일: _concept.md

용도: 기술 개념, 아키텍처, 설계 철학 설명

사용 시점:

새로운 기술 스택 도입 시
아키텍처 패턴 설명
설계 원칙 및 철학 공유
기술적 의사결정 기록

예시:

마이크로서비스 아키텍처 개념
이벤트 기반 아키텍처
CQRS 패턴
캐싱 전략

특징:

개념 간 비교 테이블 제공
사용 사례 및 실전 적용 가이드
Do/Don't 베스트 프랙티스
용어 정리 섹션
검토 주기: 6개월 (biannual)

5. FAQ 템플릿 (FAQ)

파일: _faq.md

용도: 자주 묻는 질문 모음

사용 시점:

반복되는 질문이 많은 주제
온보딩 과정에서 자주 나오는 질문
고객 지원 문서
제품 사용법 Q&A

예시:

Slack 봇 사용 FAQ
API 사용 FAQ
권한 관리 FAQ
결제/청구 FAQ

특징:

카테고리별 질문 분류
질문마다 관련 문서 링크 제공
피드백 수집 방법 안내
변경 이력 추적
검토 주기: 1개월 (monthly)

6. 팀 워크플로우 템플릿 (Team Workflow)

파일: _team-workflow.md

용도: 팀 단위 업무 방식, 협업 프로토콜

사용 시점:

팀 운영 방식 정립
크로스펑셔널 협업 정의
팀 온보딩 자료
팀 프로세스 개선 시

예시:

개발팀 스프린트 워크플로우
디자인 시스템 운영 워크플로우
데이터팀 분석 요청 워크플로우
CS팀 티켓 처리 워크플로우

특징:

역할과 책임 명확히 정의
커뮤니케이션 프로토콜 포함
SLA 및 품질 기준 명시
성과 측정 및 KPI 정의
온보딩 체크리스트 제공
검토 주기: 3개월 (quarterly)

템플릿 사용 방법

1. 템플릿 선택

위 섹션을 참고하여 작성하려는 문서에 가장 적합한 템플릿을 선택합니다.

2. 템플릿 복사

# 예: Policy 문서 작성
cp wiki/reference/templates/_policy.md wiki/policies/my-new-policy.md

# 예: How-to 가이드 작성
cp wiki/reference/templates/_how-to.md wiki/how-to/setup-dev-environment.md

3. 내용 작성

템플릿의 {placeholder} 부분을 실제 내용으로 채웁니다.

필수 수정 항목:

YAML frontmatter (제목, 소유자, 팀, 날짜 등)
TL;DR 섹션
모든 {placeholder} 항목

선택 수정 항목:

섹션 추가/제거 (필요에 따라)
예시 및 코드 블록
다이어그램

4. 메타데이터 설정

YAML frontmatter를 올바르게 설정합니다:

---
title: "문서 제목"
type: policy # policy, process, how-to, concept, faq, team-workflow
owner: "담당자 이름"
team: "담당 팀명"
audience: ["대상 독자"]
created: "2025-02-03" # 작성일
last_reviewed: "2025-02-03" # 마지막 검토일
review_cycle: monthly # monthly, quarterly, biannual, annual
status: draft # draft, review, approved, deprecated
tags: ["태그1", "태그2"]
related_docs: ["../path/to/doc.md"]
---

5. 검토 및 승인

문서 작성 후 검토 프로세스를 따릅니다:

자체 검토: 체크리스트 확인
동료 검토: 팀원 리뷰 요청
승인: 문서 오너 승인
배포: status를 approved로 변경

문서 작성 체크리스트

모든 문서는 배포 전 다음 항목을 확인해야 합니다:

필수 항목

YAML frontmatter가 완전히 채워짐
TL;DR 섹션이 3-5줄로 작성됨
모든 {placeholder}가 실제 내용으로 대체됨
관련 문서 링크가 올바르게 동작함
코드 예시가 실행 가능하고 정확함
맞춤법 및 문법 검토 완료

권장 항목

다이어그램이나 스크린샷 포함 (해당 시)
실제 사용 예시 제공
FAQ 섹션 작성 (최소 3개 질문)
관련 문서 최소 2개 이상 링크
문서 정보 섹션 완성

품질 체크

대상 독자가 이해하기 쉬운 언어 사용
단계별 설명이 명확하고 순차적
예외 상황 및 문제 해결 방법 포함
최신 정보 반영 (날짜, 버전 등)

문서 유지보수

검토 주기

각 문서 타입별 권장 검토 주기:

문서 타입	검토 주기	이유
How-to	1개월 (monthly)	기술 변화가 빠름
FAQ	1개월 (monthly)	질문이 자주 업데이트됨
Process	3개월 (quarterly)	프로세스 개선 반영
Team Workflow	3개월 (quarterly)	팀 운영 방식 변화
Policy	6개월 (biannual)	정책 변경이 덜 빈번함
Concept	6개월 (biannual)	개념은 상대적으로 안정적

상태 관리

문서 상태(status 필드):

draft: 작성 중
review: 검토 중
approved: 승인됨 (사용 가능)
deprecated: 폐기됨 (사용 중단)

폐기 프로세스

문서를 폐기할 때:

status를 deprecated로 변경

상단에 폐기 안내 추가:

> ⚠️ **폐기됨**: 이 문서는 [새 문서](link)로 대체되었습니다.

대체 문서 링크 명시
3개월 후 아카이브로 이동

템플릿 커스터마이징

프로젝트나 팀의 필요에 따라 템플릿을 커스터마이징할 수 있습니다:

섹션 추가

팀 특화 섹션 추가 예시:

## 보안 고려사항

{보안 관련 내용}

## 규정 준수

{컴플라이언스 관련 내용}

섹션 제거

불필요한 섹션은 제거 가능합니다. 단, 다음 섹션은 필수:

TL;DR
주요 내용 섹션
관련 문서
문서 정보

커스텀 메타데이터

YAML frontmatter에 프로젝트 특화 필드 추가 가능:

---
# ... 기본 필드들 ...
custom_field: "커스텀 값"
compliance_level: "high"
security_reviewed: true
---

도구 및 리소스

마크다운 에디터

VS Code + Markdown All in One 확장
Typora
Notion (Markdown 내보내기 지원)

다이어그램 도구

Mermaid (코드로 다이어그램 작성)
Draw.io (시각적 다이어그램)
Excalidraw (손그림 스타일)

검증 도구

Markdownlint (마크다운 린팅)
Vale (문서 스타일 체커)
Grammarly (맞춤법 및 문법 검사)

FAQ

Q: 어떤 템플릿을 사용해야 할지 모르겠어요. A: 작성하려는 문서의 목적을 먼저 생각해보세요:

규칙이나 기준을 정하려면 → Policy
절차를 설명하려면 → Process
방법을 알려주려면 → How-to
개념을 설명하려면 → Concept
질문에 답하려면 → FAQ
팀 운영을 정의하려면 → Team Workflow

Q: 템플릿을 수정해도 되나요? A: 네, 프로젝트나 팀의 필요에 맞게 커스터마이징할 수 있습니다. 단, 핵심 섹션(TL;DR, 주요 내용, 관련 문서, 문서 정보)은 유지하는 것을 권장합니다.

Q: 여러 템플릿의 특징을 혼합할 수 있나요? A: 가능하지만, 하나의 주된 템플릿을 선택하고 필요한 섹션만 추가하는 것이 좋습니다. 너무 많은 혼합은 문서를 복잡하게 만들 수 있습니다.

Q: 문서 검토 주기를 지키지 못하면 어떻게 되나요? A: 검토 주기는 권장사항입니다. 중요한 것은 문서가 최신 상태를 유지하는 것입니다. 검토가 늦어지면 다음 검토 때 더 철저히 확인하세요.

Q: 한글과 영어 중 어떤 언어로 작성해야 하나요? A: 조직의 공용어에 따르세요. Kyndof OS는 한글을 기본으로 하되, 기술 용어는 영어를 병기하는 것을 권장합니다.

기여 방법

템플릿 개선 아이디어가 있다면:

이슈 생성하여 개선 제안
PR로 템플릿 수정 제출
문서 오너 검토 및 승인

문서 정보

항목	내용
작성자/오너	Documentation Team
담당 팀	Product Team
마지막 검토일	2025-02-03
상태	approved

개요​

사용 가능한 템플릿​

1. 정책 템플릿 (Policy)​

2. 프로세스 템플릿 (Process)​

3. How-to 템플릿 (How-to/Runbook)​

4. 개념 템플릿 (Concept)​

5. FAQ 템플릿 (FAQ)​

6. 팀 워크플로우 템플릿 (Team Workflow)​

템플릿 사용 방법​

1. 템플릿 선택​

2. 템플릿 복사​

3. 내용 작성​

4. 메타데이터 설정​

5. 검토 및 승인​

문서 작성 체크리스트​

필수 항목​

권장 항목​

품질 체크​

문서 유지보수​

검토 주기​

상태 관리​

폐기 프로세스​

템플릿 커스터마이징​

섹션 추가​

섹션 제거​

커스텀 메타데이터​

도구 및 리소스​

마크다운 에디터​

다이어그램 도구​

검증 도구​

FAQ​

기여 방법​

관련 문서​

문서 정보​

개요

사용 가능한 템플릿

1. 정책 템플릿 (Policy)

2. 프로세스 템플릿 (Process)

3. How-to 템플릿 (How-to/Runbook)

4. 개념 템플릿 (Concept)

5. FAQ 템플릿 (FAQ)

6. 팀 워크플로우 템플릿 (Team Workflow)

템플릿 사용 방법

1. 템플릿 선택

2. 템플릿 복사

3. 내용 작성

4. 메타데이터 설정

5. 검토 및 승인

문서 작성 체크리스트

필수 항목

권장 항목

품질 체크

문서 유지보수

검토 주기

상태 관리

폐기 프로세스

템플릿 커스터마이징

섹션 추가

섹션 제거

커스텀 메타데이터

도구 및 리소스

마크다운 에디터

다이어그램 도구

검증 도구

FAQ

기여 방법

관련 문서

문서 정보