자주 쓰는 예시로 명령어 사용법을 보여 주는 짧은 설명 페이지 쓰기

## 같은 페이지가 있는지 찾은 뒤, 쓸 수 있는 OS에 맞춰 둘 곳 정하기 무언가를 만들기 전에 모든 원문 및 번역 페이지 트리에서 해당 명령어를 검색하십시오. 페이지가 이미 있다면 중복 페이지를 만들지 말고 기존 페이지를 편집하십시오. 없다면 문서화된 구문이 실제로 어디에서 작동하는지 확인하십시오. - 동일한 구문이 최소 2개 플랫폼에서 작동할 때만 명령어를 공용 디렉터리에 배치하십시오. - 1개 플랫폼에서 작동하는 명령어는 해당 플랫폼의 디렉터리에 배치하십시오. - 영어 페이지는 기본 페이지 트리에 두고, 번역 페이지는 플랫폼 경로가 동일한 언어별 트리에 두십시오. - 플랫폼별 정책에서 페이지 제목이나 호출 시 명령어의 정식 대소문자 표기를 요구하는 경우를 제외하고 파일 이름은 소문자로 작성하십시오. 명령어의 평판이나 이름만으로 디렉터리를 선택하지 마십시오. 먼저 지원 플랫폼과 구문을 검증하십시오. ## 페이지를 짧게 하고, 제목과 설명을 예시 앞에 두기 각 페이지를 다음 고정 순서에 따른 작은 Markdown 참조 문서로 작성하십시오. 1. 명령어 이름이 파일 이름과 일치하는 H1을 하나만 둡니다. 저장소에서 허용하는 경우에는 대소문자 차이를 무시합니다. 2. 인용문 형식의 설명을 가능하면 1줄이나 2줄로 작성합니다. 3. 꺾쇠괄호로 감싼 원본 제공처 URL이 포함된 필수 “추가 정보” 행을 둡니다. 4. 실용적인 예시를 둡니다. 각 예시는 명령형의 글머리표 설명 뒤에 인라인 코드 형식의 명령어 행을 별도로 배치합니다. 5. 파일 끝에 줄 바꿈 문자를 둡니다. 기본적으로 예시 5개를 사용하고 절대로 8개를 초과하지 마십시오. 설명과 명령어 사이 및 각 예시 사이에 빈 줄을 두십시오. 페이지 내용에 굵게, 기울임꼴 또는 장식용 Markdown을 사용하지 마십시오. ## 가장 흔한 실제 작업에 쓰는 예시 고르기 가장 일반적인 실제 작업을 해결하는 예시를 선택하십시오. 설명은 “파일을 나열하세요”처럼 명령형으로 작성하고 “파일을 나열합니다”처럼 서술형으로 작성하지 마십시오. 짧고 행동 중심으로 유지하며 일반적인 운영 체제 개념을 설명하지 마십시오. 각 예시를 명령어 설명서, 내장 도움말 또는 공식 문서와 대조해 검증하십시오. 문서에 명시된 옵션과 인수 사이의 간격을 유지하고, 명령어에서 다른 형식을 명시적으로 요구하지 않는 한 `--option arg`를 사용하십시오. 해당 호출 방식이 존재한다면 “도움말 표시”와 “버전 표시”를 이 순서대로 마지막 2개 예시에 배치하십시오. 우선순위가 낮은 예시이므로, 더 유용한 실용 예시가 필요하고 페이지 한도를 초과하게 된다면 둘 중 하나를 생략하십시오. ## 사용자가 바꿔 넣을 부분을 이중 중괄호로 표시하기 대체 가능한 값을 이중 중괄호로 감싸십시오. 의미에 따라 다음 자리표시자 형식을 일관되게 사용하십시오. - 파일 시스템 입력에는 `{{path/to/file}}`, `{{path/to/directory}}`, `{{filename}}`을 사용합니다. - 여러 인수에는 `{{file1 file2 ...}}`를 사용합니다. - 대안에는 `{{option1|option2}}`를 사용합니다. - 숫자 범위에는 `{{1..5}}`, 와일드카드 패턴에는 `{{*.ext}}`를 사용합니다. - 동일한 짧은 옵션과 긴 옵션에는 `{{[-v|--verbose]}}`를 사용합니다. - 함께 묶인 플래그에는 `{{[-it|--interactive --tty]}}`를 사용합니다. 짧은 형식과 긴 형식이 모두 있다면 둘 다 표시하십시오. 짧은 형식을 임의로 만들지 마십시오. 버전 플래그와 기타 일반적인 옵션은 명령어마다 다릅니다. 자리표시자를 중첩하거나 필수 이중 중괄호 구문을 단일 중괄호나 대괄호로 대체하지 마십시오. 키 입력에는 꺾쇠괄호를 사용하십시오. `<a>`, `<Enter>`, `<Space>`, `<Ctrl>`, `<Alt>`, `<Shift>`로 작성합니다. 조합은 `<Ctrl c>`처럼 공백으로 구분하고, 연속 입력은 `<Esc><u>`처럼 그룹을 서로 붙여 작성하십시오. ## 링크가 열리는지 확인한 뒤 공식 매뉴얼에 연결하기 모든 페이지에는 추가 정보 링크가 있어야 합니다. 명령어의 공식 설명서, 프로젝트 문서, 유지 관리되는 매뉴얼 페이지 서비스 또는 플랫폼 공급업체 문서를 우선하십시오. 링크를 채택하기 전에 리디렉션을 따라가 최종 응답이 성공하는지 확인하십시오. 그럴듯해 보인다는 이유만으로 URL을 신뢰하지 마십시오. 꺾쇠괄호로 감싼 링크는 전용 “추가 정보” 행에 유지하고, 1차 출처가 있다면 홍보성 또는 비공식 출처를 피하십시오. 동일한 권위 있는 출처를 사용하여 명령어 이름, 옵션 형식, 인수 간격, 플랫폼 동작, 도움말 구문, 버전 구문을 확인하십시오. ## 경로와 변수를 Windows 등 OS별 방식에 맞춰 쓰기 Windows 명령어 페이지에서는 저장소 정책에 다른 규정이 없는 한 파일 이름을 소문자로 유지하되, H1과 예시에서는 명령어의 정식 대소문자 표기를 보존하십시오. 경로 자리표시자에는 역슬래시를 사용하십시오. 환경 변수는 문서화된 셸의 구문으로 작성하십시오. 기존 명령어 인터프리터에는 `%VARIABLE%`, PowerShell에는 `$Env:VARIABLE`을 사용합니다. PowerShell용 예시는 페이지에서 더 좁은 요구 사항을 선언하지 않는 한 지원되는 가장 오래된 에디션과 현재 에디션 모두에서 작동해야 합니다. 다른 플랫폼에서는 해당 환경의 기본 경로, 셸, 환경 변수, 옵션 규칙을 따르십시오. 공용 페이지는 제시한 명령어 구문이 실제로 이식 가능할 때만 유효합니다. ## 명령어의 다른 이름과 하위 명령어마다 페이지 만들기 저장소에 별칭 도우미가 있다면 이를 사용하여 별칭 페이지를 만드십시오. 해당 명령어가 별칭임을 밝히고, 원본 제공처 정보로 연결되는 링크를 추가하며, 원래 명령어의 참조 페이지를 여는 예시를 1개 제공하십시오. 번역된 별칭 페이지의 생성 구조를 개별적으로 편집하지 말고 동일한 도우미를 통해 동기화하십시오. 하위 명령어가 있는 명령어에서는 별도 페이지를 가진 대표적인 하위 명령어를 상위 페이지 설명에 언급하십시오. 문서화된 각 하위 명령어에는 하이픈으로 구분된 자체 페이지를 만들고, 해당 하위 명령어 참조 페이지를 여는 예시를 포함하십시오. 자체 페이지에 속하는 상세한 하위 명령어 작업 흐름을 상위 페이지에 과도하게 담지 마십시오. ## 명령어와 페이지 구조를 바꾸지 않고 번역하기 영어 페이지가 존재한 후에만 번역하십시오. 예시 구조, 플랫폼 경로, 명령어, 자리표시자를 동일하게 유지하십시오. 예시용으로 예약된 도메인은 변경하지 말고, 저장소 정책에서 요구하면 자리표시자 안의 단어를 원문 언어로 유지하십시오. 영어 문법을 기계적으로 복사하지 말고 언어별 작성 규칙을 적용하십시오. 예를 들면 다음과 같습니다. - 중국어는 라틴 문자 및 숫자와 중국어 사이를 공백으로 구분하고 전각 문장 부호를 사용합니다. - 프랑스어는 예시 설명에 3인칭을 사용하고 필요한 문장 부호 앞에 공백을 둡니다. - 스페인어는 3인칭 설명과 선호되는 현지화 기술 용어를 사용합니다. - 브라질 포르투갈어와 유럽 포르투갈어는 3인칭 설명을 사용합니다. - 인도네시아어는 불필요한 동사 접두사 없이 간결한 명령어 설명 형식을 사용합니다. 영어 원문과 동일한 구조 검사로 번역 페이지를 검증하십시오. ## 사람이 검토하기 전에 검사 도구로 페이지 확인하기 사람의 검토를 요청하기 전에 변경한 파일에 저장소의 페이지 linter를 실행하십시오. 변경 사항이나 저장소 정책에서 요구할 때만 전체 트리 lint를 사용하십시오. 다음 항목을 기준으로 페이지를 검토하십시오. - 제목과 파일 이름이 일치합니다. - 인용문 형식의 설명이 짧고 유효한 정보 링크가 있습니다. - 권장 예시가 5개이며 8개를 초과하지 않습니다. - 설명이 명령형이고 빈 줄이 올바릅니다. - 옵션 형식이 검증되었고 이중 중괄호 자리표시자가 사용되었습니다. - 플랫폼 디렉터리와 해당 환경의 기본 구문이 올바릅니다. - 도움말과 버전 예시를 포함했다면 마지막 위치에 있습니다. - 장식용 서식이 없습니다. - 번역이 언어별 규칙을 따릅니다. - 파일 끝에 줄 바꿈 문자가 있습니다. 저장소의 유지 관리 스크립트가 있다면 기계적인 제목, 링크, 별칭, 상호 참조, 명령어 업데이트에 사용하십시오. 광범위한 스크립트 변경 전에 dry-run 모드를 우선하십시오. ## 쓰기 전에 AI에게 매뉴얼과 비슷한 페이지 건네기 초안을 작성하기 전에 근거를 제공하여 AI 비용과 수정 주기를 줄이십시오. 에이전트에게 규칙을 기억하도록 요구하지 말고, 명령어의 도움말 또는 설명서 출력, 승인된 유사 페이지 2개나 3개, 페이지 템플릿을 제공하십시오. 먼저 기존 페이지가 있는지 확인하십시오. 관련 페이지 요청이 맥락을 공유한다면 한꺼번에 처리하되, 각 페이지는 개별적으로 검토하십시오. 예시 8개 한도를 채우려 하지 말고 가치가 높은 예시 5개나 6개를 작성하십시오. 형식 오류가 검토자의 주의를 소모하지 않도록 사람의 검토 전에 linter를 실행하십시오. 비용은 더 나은 입력, 재사용, 결정론적 검증으로 절감해야 하며, 출처 검증을 건너뛰거나 페이지 품질을 낮추어 절감해서는 안 됩니다.