콘텐츠 모델에서는 GitHub Docs에서 만드는 각 콘텐츠 형식의 목적과 문서를 작성하거나 업데이트할 때 포함할 내용을 설명합니다. 콘텐츠 모델을 사용하여 콘텐츠가 GitHub을(를) 통해 목표를 달성하는 데 필요한 정보를 일관되고 명확하며 포괄적으로 전달하도록 합니다.
모든 설명서 집합에서 이러한 형식을 사용하여 일관된 사용자 환경을 제공하며, 모든 콘텐츠 형식은 모든 제품 또는 대상 그룹에 적용됩니다. 콘텐츠 형식은 시간이 지남에 따라 더 나아지고 필요에 따라 새 형식을 추가합니다. 해당 모델을 따르는 콘텐츠만 게시합니다.
일관성은 사람들이 문서의 정신 모델을 형성하고 시간이 지남에 따라 GitHub Docs로 돌아갈 때 필요한 정보를 찾는 방법을 이해하는 데 도움이 됩니다. 또한 일관된 콘텐츠를 유지 보수하고 업데이트하는 것이 더 효율적이므로 첫 번째 커밋을 오픈 소스 기여자이거나 또는 전체 신제품을 문서화하는 GitHub 직원의 작성자이든 문서를 보다 쉽고 빠르게 작성할 수 있습니다.
콘텐츠 구조
문서는 사이트에서 다중 수준의 계층 구조로 구성됩니다.
- 최상위 문서 집합
- 범주
- 맵 토픽
- 문서
- 문서
- 맵 토픽
- 문서
- 범주
콘텐츠를 구성할 시 사람들이 원하는 것을 찾는 데 도움이 되도록 특정 그룹을 만드는 동시에 사람들이 검색하고자 하는 정보의 깊이를 제한해야 합니다. 여러 주제가 뒤섞인 깊은 계층 구조를 통해서는 특정 문서를 찾기 어려울 수 있습니다. 같은 수준의 카테고리나 글이 많은 넓은 계층 구조를 통해서는 사람들이 무엇을 선택해야 할지 평가하고 결정하기 어렵게 만듭니다.
홈페이지 콘텐츠
GitHub Docs 홈페이지, docs.github.com은 사람들이 찾으려는 가장 중요한 항목을 강조 표시합니다. 홈페이지의 문서 집합 수를 제한하여 사용자가 정보를 찾을 수 있고 홈페이지가 과밀해지고 검색이 어려워지지 않도록 합니다.
홈페이지는 모든 최상위 문서 집합과 일부 범주를 포함합니다. 홈페이지의 콘텐츠는 GitHub 개념 및 사례를 중심으로 구성됩니다. 예를 들어 ‘CI/CD 및 DevOps’ 그룹은 GitHub Actions, GitHub Packages, GitHub Pages에 대한 최상위 문서 집합이 있습니다.
홈페이지에 문서 집합 추가하기
홈페이지의 목표는 사용자가 알아보려는 GitHub 기능 또는 제품에 대한 정보를 찾을 수 있도록 돕는 것입니다. 홈페이지에 추가된 모든 항목은 다른 모든 항목의 검색 가능성을 희석하므로, 홈페이지에 포함된 문서 집합의 수를 제한합니다.
최상위 문서 집합이 새로 만들어지면, 홈페이지에 추가됩니다.
범주가 GitHub 제품 또는 기능을 사용하기 위한 시작점으로 사용되는 경우, 홈페이지에 추가할 수 있습니다.
예를 들어 홈페이지의 ‘보안’ 그룹화에서 코드 보안 최상위 문서 집합 외에도 공급망 보안, 보안 권고, Dependabot, Code scanning, Secret scanning 범주는 각 범주가 GitHub 제품 및 기능의 진입점이기 때문에 포함됩니다. 보안 개요는 코드 보안 제품 사용에 대한 추가 정보를 제공하고 제품 또는 기능을 소개하지 않으므로 홈페이지에 포함되지 않습니다.
최상위 문서 집합
최상위 문서 집합은 GitHub 제품, 기능 또는 핵심 워크플로를 중심으로 구성됩니다. 모든 최상위 문서 집합은 GitHub Docs 홈페이지에 표시됩니다. 새 문서 집합에 포함할 콘텐츠가 많고, 맵 토픽으로 세분화된 여러 범주가 있고, 항목이 제품, 기능 또는 계정 유형에 적용되는 경우에만 최상위 문서 집합을 만들어야 합니다. 콘텐츠가 기존 최상위 문서 집합에 맞을 수 있다면, 해당 기존 문서 집합에 속할 수 있습니다.
- 최상위 문서 집합은 서로 거의 같은 중요도입니다(각각은 GitHub 제품 또는 주요 기능을 중심으로 함).
- 중대한 예외가 없는 한, 대부분의 최상위 문서 집합에는 방문 페이지 레이아웃이 있습니다. 예를 들어 사이트 정책 문서 집합에는 다른 문서 집합과 같은 가이드 또는 절차 문서가 없으므로 방문 페이지 레이아웃을 사용하지 않습니다.
- 최상위 문서 집합에는 범주, 매핑 주제 또는 문서가 혼합되어 포함될 수 있습니다.
최상위 문서 집합의 제목
- 기능 또는 제품 기반.
- 다른 사용자가 사용하고 있는 GitHub의 일부를 설명하세요.
- 예제
범주
범주는 제품 테마에 맞춰 정렬된 최상위 문서 집합 내의 기능 또는 분할 작업 집합을 중심으로 구성됩니다. 범주의 주제는 좁아서 콘텐츠 관리가 충분히 가능하고 사용하기에 너무 클 정도로 키우지 않습니다. 일부 범주는 홈페이지 상에 표시됩니다.
- 카테고리는 흔히 작게 시작하고 제품으로 성장합니다.
- 범주에는 보다 구체적인 사용자 경험 또는 작업에 대한 콘텐츠를 세분화하기 위한 맵 토픽이 포함될 수 있습니다.
- 긴 절차 문서를 사용하여 관련 콘텐츠 청크를 그룹화하고 범주 내의 문서를 간소화된 상태로 유지합니다.
- 범주에 열 개 이상의 문서가 있는 경우 콘텐츠를 맵 토픽 또는 추가 범주로 나누는 것이 좋습니다.
- 범주에는 매핑 주제 또는 문서가 혼합되어 포함될 수 있습니다.
범주의 제목
- 작업 기반(동명사로 시작).
- 기능 또는 제품을 사용하는 큰 그림의 용도 또는 목표를 설명하세요.
- 향후 제품 향상을 통해 확장할 수 있을 만큼 일반적이거나 높은 수준이어야 합니다.
- 범주 제목은 67자 이하여야 하며
shortTitle은(는) 27자 미만이어야 합니다. - 예제
범주의 소개
모든 범주는 소개가 있습니다. 소개는 한 문장 길이로 향후 제품 변경에 따라 확장할 수 있을 만큼 일반적이거나 높은 수준이어야 합니다. 범주의 구조를 크게 변경하는 경우, 업데이트가 필요한 소개를 검사하세요.
맵 토픽
맵 토픽에서는 범주의 구역을 소개하고, 범주 내의 문서를 범주의 더 큰 작업의 일부인 보다 구체적인 워크플로 또는 주체를 중심으로 그룹화합니다.
맵 토픽에는 두 개 이상의 문서가 포함되어 있습니다. 맵 토픽에 여덟 개 이상의 문서가 있는 경우, 콘텐츠를 보다 구체적인 맵 토픽으로 나누는 것이 유용할 수 있습니다.
일반적으로 특정 사용자의 요구를 충족하는 가장 좋은 방법이 아닌 한 맵 토픽 내에 맵 토픽을 포함하지 않는 것이 좋습니다.
맵 토픽의 제목
- 작업 기반(동명사로 시작).
- 범주의 더 큰 워크플로 내에서 보다 구체적인 작업을 설명하세요.
- 향후 제품 추가로 확장할 수 있을 만큼 일반적이거나 높은 수준이어야 합니다.
- 맵 토픽 제목은 63자 이하여야 하며
shortTitle은(는) 30자 미만이어야 합니다. - 예제
맵 토픽의 소개
모든 맵 토픽에는 소개가 있습니다. 소개는 한 문장 길이로 향후 제품 변경에 따라 확장할 수 있을 만큼 일반적이거나 높은 수준이어야 합니다. 맵 토픽에서 문서를 추가하거나 제거하는 경우, 업데이트가 필요한 소개를 검사하세요.
문서
문서는 GitHub Docs의 기본 콘텐츠 단위로, 여러 콘텐츠 형식을 사용하지만 모두 문서로 게시됩니다. 각 콘텐츠 형식에는 고유한 용도, 형식 및 구조가 있지만, 소개와 같은 모든 문서 형식에 표준 요소를 사용하여 문서가 일관된 사용자 환경을 제공하도록 합니다.
콘텐츠 순서
범주, 맵 토픽 및 문서 내에서 콘텐츠를 예측 가능하게 구성합니다. 가장 광범위한 적용 가능성부터 가장 구체적인 정보, 좁은 정보 또는 고급 정보에 이르기까지, 다음 순서에 따릅니다.
- 개념적 콘텐츠
- 참조 콘텐츠
- 기능 또는 설정을 사용하도록 하는 절차 콘텐츠
- 기능 사용에 관한 절차 콘텐츠
- 기능 또는 설정 관리에 관한 절차 콘텐츠
- 기능 또는 설정을 사용하지 않게 설정하는 절차 콘텐츠
- 파괴적인 작업에 관한 절차 콘텐츠(예: 삭제)
- 문제 해결 정보
콘텐츠 재사용
재사용 가능한 변수 문자열을 사용하여 절차 단계 또는 개념적 단락과 같은 동일한 콘텐츠 청크를 여러 위치에서 이용합니다. 일반적으로 특정 이유 없이 많은 문서 구역을 재사용하지 않습니다. 문서의 전체 구역이 둘 이상의 문서에서 관련될 수 있는 경우, 두 문서의 용도를 모두 살펴보세요. 하나의 긴 형식의 문서를 만들 수 있어 보이나요? 정보를 위한 최고의 영구 홈을 명확히 하려면 콘텐츠 모델을 참조하고, 다른 문서에서 해당 위치를 연결하세요.