GitHub Docs 문서의 내용

문서 구조 정보

문서 내에는 콘텐츠 섹션의 표준 순서가 있습니다. 모든 문서에는 필수 요소가 포함되어 있습니다. 문서에는 콘텐츠 디자인 또는 콘텐츠 생성에서 설명한 조건부 요소와 선택적 요소도 포함됩니다. 자세한 내용은 아래 지침을 참조하세요.

제목, 소개, 사용 권한, 제품 설명, 개념 섹션, 절차 섹션, 목차에 레이블이 지정된 문서의 스크린샷.

제목

제목은 페이지에 대한 내용과 사용자가 해당 페이지를 읽고 학습할 수 있는 내용을 완전하게 설명합니다.

제목은 어려울 수 있습니다. 다음의 일반적인 지침을 사용하여 명확하고 유용하며 서술적인 제목을 만들 수 있습니다. 이 문서의 각 콘텐츠 형식에 대한 지침에서는 보다 구체적인 제목 규칙을 제공합니다.

모든 콘텐츠 형식의 제목

제목은 페이지의 내용을 명확하게 설명합니다. 서술적이고 구체적이어야 합니다.
- 올바른 사용: "워크플로 편집기에서 액션 찾아보기"
- 올바른 사용: "코드스페이스 구성 예시"
- 잘못된 사용: "워크플로 편집기 사이드바 사용하기"
- 잘못된 사용: "예시"
제목은 이해하기 쉽고 사이트에서 렌더링하기 쉽도록 길이에 대한 엄격한 제한이 있습니다.
- 범주 제목: 67자 및 shortTitle 26자
- 맵 토픽 제목: 63자 및 shortTitle 29자
- 문서 제목: 80자, 가급적이면 60자, shortTitle 30자, 이상적으로는 20~25자
제목은 문장 대/소문자를 사용합니다.
- 올바른 사용: "Changing a commit message"(커밋 메시지 변경)
- 잘못된 사용: "Changing A Commit Message"(커밋 메시지 변경)
제목은 각 콘텐츠 형식 내에서 일관되게 유지합니다. 각 콘텐츠 형식에 해당하는 지침을 확인하세요.
제목은 제품 변경에 따라 변경되거나, 문서 내의 모든 콘텐츠를 반영하거나, 여러 제품의 콘텐츠를 포함할 수 있을 만큼 일반적이어야 합니다.
- 올바른 예: "GitHub의 청구 플랜"
- 잘못된 예: "사용자 및 조직 계정에 대한 청구 플랜"
제목은 일관된 용어를 사용합니다.
- 범주 내 또는 유사한 주제에 대한 패턴을 개발하고 준수하세요.
제목은 제품 자체의 용어를 사용합니다.
제목과 소개를 동시에 작성하세요.
- 소개를 사용하여 제목에 제시된 아이디어를 전개합니다.
- 자세한 내용은 소개에 대한 지침을 참조하세요.
제목을 정하기 어려운 경우 콘텐츠 형식을 고려합니다. 제목을 선택하는 데 문제가 있는 경우 다른 콘텐츠 형식이 더 적합할 수 있습니다.
제목이 여러 제품에 대한 검색 결과에 어떻게 표시될지 생각해 보세요.
- 사람들이 다른 제품에 대한 콘텐츠로 오해하지 않도록 제목이나 소개에 포함해야 하는 특정 단어는 무엇인가요?
프로덕션에서 제목이 어떻게 보이는지 생각해 보세요.

소개

모든 페이지의 맨 위에는 컨텍스트를 제공하고 기대치를 설정하는 소개가 있어 독자는 해당 페이지가 자신과 관련이 있는지 빠르게 판단할 수 있습니다. 소개는 검색 결과에도 표시되어 독자가 결과를 선택할 수 있도록 컨텍스트 정보를 제공합니다.

소개 작성 방법

문서 소개는 문장 1~2개 길이로 작성합니다.
맵 토픽 및 범주 소개는 한 문장 길이로 작성합니다.
API 참조 소개는 한 문장 길이로 작성합니다.
- API 페이지에 대한 소개는 전체 문서를 읽지 않고도 해당 기능이 자신의 요구 사항에 맞는지 알 수 있도록 기능을 정의해야 합니다.
소개에는 페이지의 콘텐츠에 대한 개략적인 요약이 포함되어 있으며, 제목에 제시된 아이디어를 더 자세히 발전시킵니다.
- 페이지의 제목에 접근하기 쉬운 동의어를 사용하여 독자가 문서의 목적을 다각적으로 이해할 수 있도록 도와줍니다. 가능하면 제목에 나온 단어를 반복하지 마세요.
소개는 상대적으로 변화가 없고 개략적이므로 자주 업데이트할 필요 없이 페이지의 콘텐츠에 대한 향후 변경 내용에 따라 조정할 수 있습니다.
검색 편의성을 위해 소개에 페이지의 주제에 대한 키워드를 포함합니다.
소개에 나온 용어에 약어가 있고 해당 문서의 다른 곳에도 사용한다면 약어를 표시합니다.
소개는 일반적으로 문서에 포함된 모든 작업에 대한 사용 권한을 포함하지 않습니다.

사용 권한문

모든 절차에는 절차에 설명된 액션을 수행하는 데 필요한 역할을 설명하는 사용 권한문이 포함되어 있어 개인이 작업을 완료할 수 있는지 여부를 이해하는 데 도움이 됩니다.

경우에 따라, 특히 독립 실행형 개념 문서에서 개념 콘텐츠에 필요한 사용 권한을 언급하는 것과 관련이 있습니다. 관련 절차에도 사용 권한문을 포함해야 합니다 (또는 모든 콘텐츠를 결합하는 더 긴 문서를 작성).

사용 권한문을 작성하는 방법

단일 사용 권한 집합이 문서의 모든 절차에 적용되는 경우, 사용 권한 프런트매터를 사용합니다.
문서에 여러 절차가 포함되어 있고 서로 다른 사용 권한이 적용되는 경우, 각 절차 전 해당하는 헤더 아래에 별도의 사용 권한문을 포함합니다.
문서 소개에 사용 권한을 포함하지 마세요.
역할은 여러 수준에 있습니다. 액션과 동일한 수준의 역할만 참조합니다. 예를 들어 보호된 분기를 구성하려면 리포지토리(또는 리포지토리 수준의 역할)에 대한 관리자 액세스 권한이 필요합니다. 조직 소유자(조직 수준 역할)로 리포지토리에 대한 관리자 액세스를 얻을 수 있지만 리포지토리 수준 역할은 실제로 액션을 수행하는 기능을 제어하기 때문에 권한문에는 리포지토리 수준 역할만 언급합니다.
사용 권한문에 사용할 언어:
- [계정 역할]은 [액션]을 수행할 수 있습니다.
- [기능]에 대한 [기능 역할] 액세스 권한이 있는 사용자는 [액션]을 수행할 수 있습니다.
- 잘못된 사용: [계정 역할]과 [기능]에 대한 [기능 역할] 액세스 권한이 있는 사용자는 [액션]을 수행할 수 있습니다.

사용 권한문 예시

여러 절차에 대한 단일 사용 권한문이 있는 문서는 엔터프라이즈에서 리포지토리 관리 정책 적용입니다.

특정 제품에서만 사용할 수 있는 기능이고 버전 관리만으로는 해당 기능의 사용 가능성을 전달할 수 없는 경우 제품 설명을 사용합니다. 예를 들어, GHEC 및 GHES에서 어떤 기능을 사용할 수 있는 경우 해당 기능에 대한 콘텐츠는 GHEC 및 GHES 전용으로 버전을 지정할 수 있습니다. Pro, Team, GHEC 및 GHES(Free 제외)에서 사용할 수 있는 기능의 경우, 제품 설명에서 해당 기능의 사용 가능성을 전달합니다.

모든 제품 설명은 재사용 가능한 gated-features 항목으로 저장되고 관련 문서에 대한 YAML 프런트매터에 추가됩니다.

제품 설명 작성 방법

제품 설명은 엄격한 형식을 따르며 기능 및 해당 기능을 사용할 수 있는 제품을 명확하게 식별합니다.
제품 설명에는 "GitHub의 제품"으로 연결되는 링크와 경우에 따라 다른 관련 문서에 대한 링크도 포함됩니다.
예:
- [기능 이름]은 [제품]에서 사용할 수 있습니다. 자세한 내용은 "GitHub의 제품"을 참조하세요.
- [기능 이름]은 [무료 제품]으로 퍼블릭 리포지토리에서 사용할 수 있으며, [유료 제품]으로 퍼블릭 및 프라이빗 리포지토리에서 사용할 수 있습니다. 자세한 내용은 "GitHub의 제품"을 참조하세요.

제품 설명이 있는 문서 예시

원본 파일 및 gated-features를 확인하여 원본 콘텐츠가 어떻게 작성되었는지 확인하세요.

분기 보호 규칙 관리

도구 전환기

일부 문서에는 GitHub CLI 또는 GitHub Desktop과(와) 같이 작업을 완료하는 데 사용하는 도구에 따라 달라지는 콘텐츠가 있습니다. 대부분의 콘텐츠의 경우 여러 도구에 대해 동일한 개념적 또는 절차상 정보를 사용합니다. 그러나 정보를 명확하고 정확하게 만드는 유일한 방법이 도구를 사용하여 콘텐츠를 구분하는 것인 경우 도구 전환기를 사용합니다. 다른 언어로 예시를 표시하는 용도로만 도구 전환기를 사용하지 마세요. 작업 또는 개념이 사용자가 사용하는 도구에 따라 변경되는 경우에만 도구 전환기를 사용하세요. 자세한 내용은 "문서에서 도구 전환기 만들기"을(를) 참조하세요.

개념적 콘텐츠

개념적 콘텐츠는 사람들이 주제를 이해하거나 학습하는 데 도움을 줍니다. 자세한 내용은 콘텐츠 모델 속 “개념 콘텐츠 형식”을(를) 참조하세요.

참조 콘텐츠

참조 콘텐츠는 제품 또는 기능을 적극적으로 사용하는 데 관련된 체계적인 정보를 제공합니다. 자세한 내용은 콘텐츠 모델 속 “참조 콘텐츠 형식”을(를) 참조하세요.

선행 조건

선행 조건은 작업을 시작하기 전에 필요한 모든 것을 준비하기 위해서 사용자가 절차를 진행하기 전에 알아야 할 정보입니다.

선행 조건을 작성하는 방법

절차의 번호가 매겨진 단계 바로 전에 선행 조건을 작성합니다.
목록, 문장 또는 단락을 사용하여 선행 조건을 설명할 수 있습니다.
다음과 같은 경우 별도의 선행 조건 섹션을 사용할 수도 있습니다.
- 선행 조건 정보는 매우 중요하며 누락하면 안되는 경우
- 둘 이상의 선행 조건이 있는 경우
데이터 손실 또는 파괴적인 액션에 대한 중요한 정보를 반복하거나 강조 표시하기 위해 경고 또는 위험 콜아웃도 사용하여 선행 조건을 공유할 수 있습니다.

선행 조건에 대한 제목 지침

별도의 섹션을 사용하는 경우 Prerequisites(이)라고 부르는 헤더를 사용합니다.

선행 조건 섹션이 있는 문서의 예

절차 콘텐츠

절차 콘텐츠는 사용자가 작업을 완료하는 데 도움을 줍니다. 자세한 내용은 콘텐츠 모델 속 “절차 콘텐츠 형식”을(를) 참조하세요.

문제 해결 콘텐츠

문제 해결 콘텐츠는 사용자가 오류를 방지하거나 해결하는 데 도움이 됩니다. 자세한 내용은 콘텐츠 모델 속 “콘텐츠 형식 문제 해결”을(를) 참조하세요.

다음 단계

문서에 큰 프로세스의 한 단계를 설명하거나 대부분의 사람들이 수행하기를 원하는 논리적인 다음 단계가 있는 경우에는 다음 단계 섹션을 포함하세요. 사용자들을 문서 또는 기타 GitHub 리소스에 연결할 수 있습니다.

다음 단계 섹션의 예

## Next steps

- You can monitor self-hosted runners and troubleshoot common issues. See "Monitoring and troubleshooting self hosted runners."

- GitHub recommends that you review security considerations for self-hosted runner machines. See "Security hardening for GitHub Actions."

"엔터프라이즈의 자체 호스트 실행기 시작"의 이 예제에서는 다음 단계 섹션에 문서에 설명된 기능을 사용하기 시작한 후 수행해야 할 절차에 대한 링크가 포함되어 있습니다.

## Next steps

After your enterprise account is created, we recommend learning more about how enterprise accounts work and configuring settings and policies. Follow the "Get started with your enterprise account" learning path.

“엔터프라이즈 계정 만들기”의 이 예제에서는 엔터프라이즈 계정 생성을 마친 대부분의 사람들이 다음 단계로 이동할 수 있는 곳으로 연결됩니다.

추가 참고 자료

사람들이 작업을 완료하거나 현재 문서에 설명된 주제를 사용하는 방법을 배우는 데 도움이 되는 추가 문서가 있으면 추가 읽기 섹션에 포함하세요. 문서 콘텐츠 내에 아직 링크되지 않은 문서에 대한 링크만 포함하세요.

당면한 작업이나 주제에 도움이 되는 링크만 포함하세요. 가능한 모든 링크를 제공하는 것보다 가치 있는 리소스를 집중적으로 제공하는 것이 더 좋습니다.

형식 추가 참고 자료 섹션으로, 순서를 지정하지 않은 목록을 사용합니다. 링크 작성 방법은 "스타일 가이드"을(를) 참조하세요.

추가 읽기 구역의 제목 및 서식

## Further reading
- "[Article title](article-URL)"
- [External resource title](external-resource-URL) in External Resource Name

이 문서의 내용