jh941213 사용자/운영자 매뉴얼 스킬
읽는 사람(최종 사용자 vs 운영자)과 읽는 상황(학습 중 vs 장애 대응 중)에 맞는 문서를 만든다.
입력
$ARGUMENTS
사용자 매뉴얼 — Diátaxis 4분면
핵심 규칙: 한 페이지에 두 모드를 섞지 않는다. 페이지를 쓰기 전에 먼저 분류하라:
| 분면 | 목적 | 형태 | 위치 |
|---|---|---|---|
| Tutorial | 학습 (처음 온 사람) | 따라하면 성공하는 수업. 선택지 없이 한 길 | docs/manuals/tutorials/ |
| How-to | 과제 해결 ("X 하려면?") | 목표 지향 단계. 전제조건 명시 | docs/manuals/how-to/ |
| Reference | 정보 조회 | 사전식. 제품 구조를 그대로 반영 | docs/manuals/reference/ |
| Explanation | 이해 ("왜 이렇게?") | 배경, 설계 이유, 트레이드오프 | docs/manuals/explanation/ |
트리거 매핑: 새 기능 → how-to + reference / 새 개념 → explanation / 온보딩 갭 → tutorial
인덱스는 docs/manuals/README.md — 4분면으로 내비게이션 구성.
운영자 매뉴얼
위치: docs/ops/
1. 운영 개요 (docs/ops/README.md)
- 시스템 토폴로지 (docs-architecture의 배포 다이어그램 링크/포함)
- 용량/스케일링 노트, 정상 상태 지표 기준선
2. 설정 레퍼런스 (docs/ops/configuration.md)
모든 환경변수/플래그를 표로 — 코드에서 추출 (.env.example, config 파일, process.env/os.environ grep):
| 이름 | 타입 | 기본값 | 효과 | 유효값 |
|---|
3. 런북 (docs/ops/runbooks/[알림명].md)
새벽 3시에 처음 보는 사람이 따라할 수 있어야 한다. 템플릿: templates/runbook.md
- 알림당 1개 파일: 알림명/심각도/사용자 영향 → 진단(대시보드 링크 + 복붙 가능한 쿼리) → 완화(순서 있는 복붙 가능 명령 + 각 단계의 트레이드오프 경고) → 근본 해결/후속 → 에스컬레이션 경로
- 새 알림 룰이 생기면 런북도 같은 PR로. 인시던트에서 사용된 런북은 사후 반드시 갱신
4. 배포 가이드 (docs/ops/deployment.md)
환경 목록, 파이프라인 설명, 롤아웃 절차, 배포 후 검증(스모크 체크 명령), 롤백 절차(가장 중요 — 복붙 가능하게)
5. 인시던트 플레이북 (docs/ops/incident-playbook.md)
심각도 매트릭스, 역할(지휘자/커뮤니케이션 담당), 커뮤니케이션 템플릿, 에스컬레이션 정책, 블레임리스 포스트모템 템플릿
실행 절차
- 대상 판별: 인자에서 사용자 문서인지 운영 문서인지, 특정 문서인지 전체인지
- 소스 수집: 코드(설정/알림 룰/배포 스크립트), 기존 docs/, CI 설정, docker/k8s 매니페스트
- 코드에서 확인한 사실만 기술 — 알 수 없는 운영 값(대시보드 URL, 온콜 로테이션)은
<!-- TODO: 운영팀 확인 -->마커로 남기고 목록으로 보고 - 기존 문서는 Edit로 갱신, 신규만 Write
docs/docs.yaml매니페스트 갱신- 설명은 한국어(또는 프로젝트 언어), 명령/식별자는 원문
제약
docs/폴더만 수정- 런북의 명령은 실제 실행 가능해야 함 — 존재하지 않는 스크립트/명령 금지
- 페이지당 Diátaxis 분면 1개 — 혼합 감지 시 분리 제안