사용자 매뉴얼
User-Manual/ 디렉토리 아래에 근거 기반의 Markdown 소스 하나를 유지합니다. 최종 사용자,
관리자/운전자 및 기술 참고서의 세 가지 에디션을 게시합니다. Markdown이 제품이며;
렌더링은 별도로 교체 가능한 단계입니다.
가장 작은 워크플로우 선택
- 새 매뉴얼: 사용자와 인터뷰하고, 리포지토리를 검사하며, 모듈 맵을 제안하고, 승인을 받은 후,
승인된 JSON 모듈 파일로
scripts/init_manual.py를 실행합니다. - 기존 매뉴얼:
User-Manual/manual.yml을 읽고, 요청된 범위와 관련 Git diff를 검사한 후, 영향을 받은 페이지만 업데이트합니다. - 적용 범위 감사:
scripts/audit_manual.py를 실행하고 모든 오류와 경고를 설명합니다. - 빌드: 감사가 통과한 후에만
scripts/build_manual.py를 실행합니다. 각 에디션을 조립한 후,manual.yml의renderer.kind에 따라 렌더링합니다:markdown(기본값),command또는mkdocs. - 신선도: 업데이트 후
scripts/manual_state.py record --feature <dir>을 실행합니다.status는 입력이나 매뉴얼 출력이 기록 이후 변경되면 exit 1을 반환합니다.
init_manual.py는 빌드, 감사 및 상태 스크립트(그리고 tools/theme/에 포함된 스타일시트)를 CI를 위해
User-Manual/tools/로 복사합니다. 이 스킬을 업그레이드한 후에는 해당 복사본을 scripts/ 디렉토리에서
새로 고치십시오. --no-tools는 CI가 스크립트를 다른 곳에서 실행할 때 복사를 건너뜁니다. CI 워크플로우는
--ci-policy <file>의 ci: 매핑을 따르며, 해당 파일이 없을 경우 .specify/workflow.yml을 따릅니다.
이 스킬은 .specify/, 기능 명세서 또는 Spec Kit 명령을 필요로 하지 않습니다. 작업 범위는 사용자의
요청, 리포지토리 증거 및 버전 관리 변경 사항을 기반으로 결정합니다.
필요한 작업만 라우팅
| 작업 | 읽을 문서 |
|---|---|
| 발견 및 인터뷰 | discovery.md |
| 페이지 구조 및 Markdown 구문 | content-model.md |
| 대상 독자 및 언어 | audience-language.md |
| 증분 변경 | incremental-update.md |
| 엔티티, 컬럼, 열거형, ER 다이어그램 | data-reference.md |
| 렌더러, 템플릿, 브랜드, HTML, PDF, RTL | publishing.md |
| API 문서 | api-docs.md |
| 릴리스 노트 및 마이그레이션 가이드 | release-docs.md |
| UI 스크린샷 | ui-screenshots.md |
| 프리뷰 및 릴리스 게시 | preview-publishing.md |
절대 지켜야 할 규칙
- 영어를 기본으로 합니다. 아랍어는 프로젝트별로 선택 사항이지만, 페이지, 렌더러, 다이어그램 및 PDF는 초기화부터 RTL을 지원해야 합니다.
- 평이하고 자연스러운 영어 또는 아랍어를 사용합니다. 선언된 대상 독자를 위해 작성하며, 최종 사용자에게 기술 설명을 그대로 재사용하지 않습니다.
- 주장은 구현, 계약, 테스트, 관찰된 동작, 스키마 또는 승인된 인프라 소스에 근거합니다. 알 수 없는 것은 표시하고, 동작을 절대 지어내지 않습니다.
- 비밀, 자격 증명, 토큰, 개인 키, 연결 문자열, 프로덕션 레코드 또는 수정되지 않은 개인 데이터를 절대 포함하지 않습니다. 결정론적 합성 예제를 사용합니다.
- 승인된 확장 가능한 모듈 맵을
User-Manual/manual.yml에 저장합니다. 이후 발견 사항은 승인될 때까지proposed로 추가합니다. - Markdown을 정규 형식으로 유지하고 GitHub의 자체 구문을 작성하여 모든 페이지가 GitHub에서 올바르게 읽히도록 합니다. 빌드는 이를 다른 렌더러용으로 변환합니다. 다른 형식은 빌드를 통해서만 생성합니다.
- 유용한 다이어그램만 생성하며,
illustrate스킬이 설치된 경우 해당 스킬을 사용합니다. 시스템 개요는 읽을 수 있는 모듈 수준 세부 정보와 분리하여 유지합니다: 시스템 ER 개요 + 더 작은 모듈 ER 다이어그램. 입증된 모든 엔티티, 컬럼, 데이터 타입, 관계, 제약 조건 및 열거형을 문서화합니다. - 소유한 마커 외부에 있는 수작업 콘텐츠를 보존하고 재실행 시 수렴하도록 합니다.
- 페이지는 해당 독자가 받는 페이지만 링크합니다. 빌드는 교차 독자 페이지 링크와 누락된 에셋을 거부하며, 에디션의 페이지가 도달하는 에셋만 스테이징하므로 한 독자는 다른 독자의 스크린샷이나 샘플을 절대 게시하지 않습니다.
실제 예시
"예약 플랫폼의 매뉴얼을 만들어 주세요"와 같은 요청이 들어오면, 라우트, 내비게이션, API, 테스트 및 스키마
파일에서 예약, 고객, 결제 및 운영 모듈을 식별합니다. 사용자에게 해당 모듈 맵을 승인해 달라고 요청합니다.
그런 다음 대상 독자별 튜토리얼, 안전한 스크린샷, API 및 데이터 참고서, 영어 콘텐츠와 선택적 아랍어 콘텐츠를
User-Manual/ 아래에 생성하고, 프로젝트가 선택한 방식(GitHub의 Markdown, Pandoc을 통한 팀 Word 템플릿,
또는 PDF가 포함된 MkDocs 사이트)으로 렌더링합니다.