reStructuredText로 실제 예시가 있는 기술 문서를 쓰고 빌드로 확인하기

## 독자에게 필요한 것을 설명하고 깊은 내부 내용은 코드에 맡기기 문서화된 동작을 이해하고 사용해야 하는 독자를 위해 작성한다. 개념을 최대한 명확하고 간결하게 설명한다. 독자의 판단에 도움이 된다면 저수준 세부 사항도 포함하되, 매우 깊은 구현 내부 사항은 소스 코드에 맡긴다. - 메서드를 올바르게 사용하는 데 시그니처가 중요할 때만 해당 메서드 시그니처를 설명한다. - 사용 가능한 모든 스위치를 나열하지 말고, 주요 작업 흐름에 영향을 주는 명령 인수와 옵션을 문서화한다. - 코드 안의 메시지가 원인과 해결 방법을 이미 명확히 설명한다면 같은 오류나 예외를 다시 설명하지 않는다. - 모든 항목을 망라한 목록보다 초점을 맞춘 설명, 현실적인 예시, 관련 세부 정보 링크를 우선한다. ## 변경 종류와 릴리스 정보로 브랜치 고르기 유지보수 중인 버전 목록을 절대 하드코딩하지 않는다. 대상 브랜치를 선택하기 전에 프로젝트의 공식 릴리스 메타데이터를 읽고, 변경 유형별 규칙을 일관되게 적용한다. - 버그 수정은 해당 버그가 존재하는 가장 오래된 유지보수 브랜치를 대상으로 한다. - 새 기능 문서는 그 기능이 도입된 브랜치를 대상으로 한다. 해당 브랜치의 유지보수가 끝났다면 그다음 유지보수 브랜치를 사용한다. - 오탈자, 문구 수정, 구조 변경 및 기타 비기능 변경은 가장 오래된 유지보수 브랜치를 대상으로 한다. - 독립적으로 버전을 관리하는 하위 프로젝트의 문서는 자체적으로 선언한 정책을 따른다. 정책에 명시되어 있다면 새 기능을 포함한 모든 변경을 가장 오래된 유지보수 브랜치에 반영한다. 변경 유형과 판단에 사용한 유지보수 데이터를 기록한다. 릴리스 메타데이터를 사용할 수 없거나 의미가 모호하다면 브랜치를 추측하지 않는다. ## 제목 기호와 줄 바꿈 길이 맞추기 제목 수준별 밑줄 문자를 일관되게 사용한다. 수준 1은 등호, 수준 2는 하이픈, 수준 3은 물결표, 수준 4는 마침표, 수준 5는 큰따옴표를 사용한다. 각 밑줄은 제목 전체 길이에 맞아야 한다. 저장소가 특정 경로에 대한 제목 예외를 선언했다면 그 예외를 적용한다. 표, URL, 고립된 줄처럼 줄바꿈이 가독성을 떨어뜨리는 경우를 제외하고 본문을 80자에서 줄바꿈한다. 목록 기호는 줄 맨 앞에 둔다. 굵게 또는 기울임으로 표시한 범위를 여러 줄에 걸쳐 나누지 않는다. 인라인 코드에는 쌍으로 된 이중 백틱을 사용한다. 기본 언어의 코드 예시에는 간결한 이중 콜론 형식을 사용하되, 마커만 한 줄을 차지하게 된다면 사용하지 않는다. 언어나 렌더링 문맥을 지정해야 할 때는 명시적인 code-block 지시어를 사용한다. ## 지시어 들여쓰기와 링크 쓰는 방식 맞추기 지시어 내용은 공백 4칸으로 들여쓴다. 이중 콜론 마커 다음에는 내용 앞에 빈 줄을 두고, 각 지시어 앞뒤에도 빈 줄을 둔다. 여러 줄로 된 목록 항목의 이어지는 줄은 항목 텍스트가 시작되는 위치에 맞춘다. 메시지에 맞는 표준 안내 지시어인 note, tip, warning, caution, seealso 중 하나를 사용한다. 버전 추가와 사용 중단에는 각각 전용 지시어를 사용하고, 관련 버전과 짧은 설명을 함께 적는다. 내부 문서 링크에는 절대 문서 경로를 사용한다. 특정 절로 연결할 때는 레이블이 있는 상호 참조를 사용한다. 상대 내부 경로는 절대 사용하지 않는다. 외부 사이트는 본문에 URL을 직접 넣지 말고 이름이 있는 링크 대상을 파일 끝에 배치한다. 언어 API의 클래스, 메서드, 함수, 내장 타입에는 문서 시스템이 제공하는 전용 역할을 사용한다. ## YAML, XML 같은 설정 예시를 늘 같은 순서로 보여 주기 기능이 여러 설정 형식을 지원한다면 configuration-block 지시어에 지원되는 모든 형식을 표시한다. 독자가 페이지마다 배치를 다시 익히지 않고 비교할 수 있도록 저장소 전체에서 순서를 통일한다. - 서비스와 일반 설정은 YAML, XML, 프로그래밍 언어 형식 순서로 제시한다. - 라우팅, 검증, 객체 매핑은 속성, YAML, XML, 프로그래밍 언어 형식 순서로 제시한다. - 번역 리소스는 XML, YAML, 프로그래밍 언어 형식 순서로 제시한다. 일반 탭은 대체 도구나 작업 흐름처럼 설정이 아닌 병렬 콘텐츠에만 사용한다. 프레임워크 통합 애플리케이션과 독립 실행형 애플리케이션의 예시가 다르다면 렌더러와 독자가 문맥을 구분할 수 있도록 서로 다른 언어 식별자를 사용한다. ## 실제 같은 이름과 파일 이름 주석으로 코드 예시 쓰기 대상 언어의 코딩 표준과 프로젝트에서 확립한 모범 사례를 따른다. 의도를 가리는 임시 단어 대신 현실적인 이름과 상황을 사용한다. 예시용으로 예약된 도메인과 저장소에서 정한 예시 공급자 이름을 사용한다. - 가능하면 코드 블록의 줄을 85자에서 줄바꿈한다. - YAML을 포함한 예시는 공백 4칸으로 들여쓴다. - 예시 실행이나 타입 이해에 도움이 된다면 네임스페이스와 import 선언을 포함한다. - 코드 블록은 파일 이름을 나타내는 주석으로 시작한다. 다음 줄도 주석인 경우가 아니면 그 사이에 빈 줄을 추가하지 않는다. - 모든 셸 명령 앞에 프롬프트 마커를 붙인다. - 생략된 블록을 접을 때는 해당 언어에 맞는 주석 형식을 사용한다. - 같은 줄에서 값의 일부를 줄일 때는 주석 마커 없이 줄임표만 사용한다. - 필요한 경우 YAML 인라인 매핑 내부의 공백을 포함해 형식별 공백 규칙을 지킨다. 예시는 프로덕션용 구현을 완전히 제공하는 것처럼 가장하지 않으면서 지원되는 경로를 알려 주어야 한다. 제시된 코드가 실패하게 만드는 전제 조건을 생략하지 않는다. ## 쉬운 미국 영어로 쓰고 simply 같은 말 피하기 미국 영어로 작성한다. 절 제목에는 타이틀 케이스를 사용한다. 첫 단어, 마지막 단어, 주요 단어는 대문자로 시작하고, 짧은 기능어는 제목 첫머리에 있지 않다면 소문자로 쓴다. “we”를 화자로 사용하지 말고 독자에게 “you”를 사용한다. 성별을 한정하지 않는 대명사를 사용한다. 전 세계 독자가 이해할 수 있도록 능동태, 기본 어휘, 직접적인 문장을 우선한다. 축약형은 허용한다. 옥스퍼드 쉼표를 사용하지 않는다. “obviously”, “simply”, “just”, “easy”, “clearly”, “trivial”, “of course”와 같은 관용적이거나 독자를 낮춰 보는 표현을 피한다. 이런 표현은 설명 부족을 감추고 독자의 의욕을 꺾을 수 있다. 모든 이미지에는 대문자로 시작하고 마침표로 끝나는 간결한 대체 텍스트가 필요하다. “A screenshot of”나 “Diagram of”로 시작하지 않는다. 모든 세부 사항을 대체 텍스트에 억지로 넣지 말고 복잡한 다이어그램은 주변 본문에서 설명한다. ## 마치기 전에 문서를 빌드해 경고와 깨진 링크 확인하기 디렉터리는 끝에 슬래시를 붙이고 파일 확장자는 앞에 마침표를 붙여 쓴다. 디렉터리 트리 예시에는 `your-project/`와 같은 중립적인 예시 프로젝트 루트를 사용한다. 본문과 예시 사이에서 파일 이름, 경로, 명령, 참조 대상을 일관되게 유지한다. 문서 변경을 완료한 것으로 간주하기 전에 다음을 수행한다. 1. 지정된 빌드 작업 공간에 문서 빌드 의존성을 설치한다. 2. 저장소에 문서화된 빌드 명령을 실행한다. 3. 시각적 검사가 필요하면 생성 결과를 임시로 제공한다. 4. 변경된 페이지에서 경고, 끊어진 참조, 잘못된 지시어, 코드 렌더링, 제목 계층, 이미지 설명을 확인한다. 5. 선택한 대상 브랜치가 변경 유형과 현재 유지보수 메타데이터에 여전히 맞는지 확인한다. 저장소가 문서 빌드 수단을 제공한다면 소스 검사만으로 성공을 보고하지 않는다.