Diosix 문서화 규칙

Diosix 문서화하기

docs/의 모든 문서 페이지와 README.md는 hypervisor/, tools/, scripts/의 구현과 100% 동기화되어야 하며, docs/style-guide.md를 준수하여 첫 번째 리뷰에서 reviewing-diosix를 통과해야 합니다.

핵심 지침

1. 명확하고 정확한 영어 산문 (기본): 모든 문서는 미국식 영어로 작성되어야 하며, 맞춤법이 검증되고 문법이 올바르며, 기술적 명확성이나 정밀성을 희생하지 않는 간결한 표현을 사용해야 합니다.
2. 문서의 진실성: docs/에 오래된 CLI 플래그, SBI 함수 ID, ioctl 번호, C 구조체 레이아웃(uint64_t vs unsigned long), 파일 경로, 구성 키를 절대 남겨두지 마십시오. 동작, CLI 옵션, 모듈 파일 경로, 구성 스키마를 변경하는 모든 코드 변경은 동일한 변경에서 docs/를 업데이트해야 합니다.
3. 이중 대상 독자 설계: 다음 두 가지 뚜렷한 독자를 명시적으로 고려해야 합니다:
   • 사용자 (초보자 및 전문가): Diosix를 부팅하고, 가이드 투어를 실행하고, dsx로 게스트 VM을 실행하거나, 선언형 시스템/헌장 매니페스트를 구성하는 운영자.
   • 개발자 및 유지보수자: M-모드 하이퍼바이저, S-모드 dynarec, U-모드 도구를 빌드, 테스트, 디버깅 및 확장하는 엔지니어.
4. 엄격한 스타일 준수 (docs/style-guide.md)
   • 산문, 목록 항목 및 코드 블록은 한 줄에 최대 80자로 줄 바꿈합니다 (마크다운 테이블 행과 긴 URL 제외). 마크다운 링크 텍스트에는 파일 기본 이름을 사용하여 ([S50dropbear](../tools/.../S50dropbear))) 링크 줄이 80열 내에서 깔끔하게 줄 바꿈되도록 합니다.
   • 능동태와 현재 시제를 사용합니다 ("하이퍼바이저가 GPA를 검증합니다", "GPA가 하이퍼바이저에 의해 검증될 것입니다" 사용 금지).
   • 문장형 제목을 사용합니다 (## 계층적 게스트 모델, ## 계층적 게스트 모델 사용 금지).
   • 페이지별 첫 사용 시 약어를 풀어씁니다 (Supervisor Binary Interface (SBI)), 그 후에는 약어만 사용합니다 (SBI).
   • 순차적 다단계 절차에는 엄격히 번호 목록을 사용하고, 비순차적 항목에는 글머리 기호 목록을 사용합니다.
5. 확실하지 않을 때는 멈추고 수석 유지보수자에게 문의: 의도한 동작, 용어, 대상 독자 범위가 모호한 경우, 추측하거나 세부 사항을 만들어 내지 말고 멈추고 수석 유지보수자에게 명확히 문의하십시오.

집중 참조 가이드

문서를 작성하거나 편집하기 전에 관련 참조 파일을 읽으십시오:

• 스타일 및 표준 용어 : 영어 문법/철자 기준, 80열 줄 바꿈, 약어 확장 규칙, 표준 하드웨어/가상화 정의 (호스트 빌드 머신, 호스트 하드웨어, 대상 플랫폼, HPA, GPA, GVA, CID).
• 이중 대상 독자 및 문서 맵 : 초보자/전문가 사용자 대 유지보수자를 위한 콘텐츠 맞춤화, 코드 변경을 특정 docs/*.md 파일에 매핑, 테스트 규칙 문서화.