vpd-permission-poc/docs/DOCUMENTATION-STANDARDS.md

문서 구조 표준

목적

문서를 처음 보는 사람이 전체 구조를 빠르게 이해하고, 필요한 순간에만 적용 방법이나 장애 해결 세부사항으로 내려갈 수 있게 한다.

기본 문서 지도

README.md              무엇을, 왜 하는가 / 현재 상태 / 큰그림
├── architecture.md    어떻게 구성되며 누가 무엇을 신뢰하는가
├── cookbook.md        어떻게 적용·검증·되돌리는가
└── troubleshooting.md 무엇이 실패했고 어떻게 진단·해결하는가

README 필수 항목

• 목적·범위·제외 범위
• 현재 상태와 검증된 사실
• 구성요소 5~7개 이하의 개요도
• 핵심 결정 3~5개
• 상세 문서 링크와 독자가 어떤 경우에 읽어야 하는지

상세 문서 규칙

문서	포함할 내용	포함하지 않을 내용
architecture.md	신뢰 경계, 구성요소 책임, 상세 흐름, 데이터 모델, 설계 근거	긴 설치 명령과 오류 이력
cookbook.md	준비물, 단계, 입력값 형식, 성공 판정, rollback, 관련 troubleshooting 링크	설계 배경의 반복
troubleshooting.md	증상, 원인, 확인 명령, 해결, 재발 방지	secret 값, 원인 없는 임시 우회

그림 규칙

• README 개요도는 경계와 흐름만 보여 주고 화살표는 가능한 한 10개 이하로 유지한다.
• 포트, claim, redirect URI, DB role처럼 세부값이 필요한 내용은 상세도 또는 표로 분리한다.
• 그림 아래에 “이 그림에서 기억할 점”을 적는다.
• Mermaid를 쓸 때는 노드 이름을 짧게 하고, 긴 설명은 표 또는 본문으로 옮긴다.

보안과 검증

• 비밀번호·secret·token·cookie는 예시에도 넣지 않는다.
• 각 cookbook 단계는 성공 판정과 다음 조치를 포함한다.
• 문서를 마칠 때는 링크 유효성, Mermaid 문법, 용어 일관성, secret 노출 여부를 점검한다.