전역 탐색
전역 탐색(글로벌 네비게이션)은 문서의 가장 왼쪽에 있는 패널입니다. 전역 네비게이션을 사용하여 콘텐츠를 탐색할 수 있습니다.
연구에 따르면 사람들은 GitLab 제품 문서를 검색하기 위해 Google을 사용합니다. 결과 페이지에 접속하면 사용자가 읽고 있는 내용과 관련된 주제를 찾아야 합니다. 전역 네비게이션은 이 정보를 제공합니다.
최상위 수준에서 우리의 전역 네비게이션은 워크플로우 기반입니다. 네비게이션은 사용자가 GitLab을 어떻게 사용할 지에 대한 사고 모델을 구축하는 데 도움이 되어야 합니다. 더 높은 워크플로우 기반 주제 아래의 수준은 각각의 기능 이름입니다. 예를 들어:
GitLab 사용 (워크플로우) > 애플리케이션 빌드 (워크플로우) > 시작하기 (기능)> CI/CD (기능) > 파이프라인 (기능)
일부 구식의 네비게이션 섹션은 알파벳순으로 구성되어 있지만, 네비게이션은 주로 워크플로우에 기반해야 합니다.
네비게이션 항목 없이:
- 페이지가 열리면 네비게이션이 닫히고, 독자는 자신의 위치를 잃게 됩니다.
- 페이지가 다른 페이지와 함께 표시되지 않습니다.
탐색 항목에 적절한 단어 선택
왼쪽 네비게이션에 항목을 추가하기 전에 사용할 품사를 선택하세요.
네비게이션 항목은 페이지 제목과 일치해야 합니다. 그러나 제목이 너무 길 경우 구절을 줄일 때 다음 중 하나를 사용하세요:
- 병합 요청과 같이 명사를 사용하세요.
- GitLab 설치 또는 런너로 시작하기와 같이 능동적인 동사를 사용하세요.
페이지가 어떤 용도인지 명확히 나타내는 구문을 사용하세요. 예를 들어, 시작하기보다는 런너로 시작하기와 같이 더 도움이 되는 구문을 사용하세요.
네비게이션 항목 추가
기술 작성자 중 하나의 동의 없이 글로벌 네비게이션에 항목을 추가하지 마세요.
글로벌 네비게이션에 주제를 추가하려면:
-
navigation.yaml파일에 항목을 추가하세요. - 기술 작성자에게 MR(Merge Request)을 할당하여 검토 및 병합하세요.
추가할 위치
문서 페이지는 다음 그룹에 속한다고 할 수 있습니다:
- GitLab 사용자. 이는 리포터(Reporter)에서 오너(Owner)까지 모든 권한을 가진 사용자를 위한 GitLab의 일상적인 사용을 위한 문서입니다.
- GitLab 관리자. 이는 GitLab을 호스팅하는 기본 인프라에 액세스가 필요한 자체 관리 인스턴스용 문서입니다.
- 기타 문서. 이는 GitLab의 일상적인 사용 이외의 고객 및 기여자를 위한 문서를 포함하며, 다른 그룹에 맞지 않는 문서를 여기에 포함합니다.
이러한 그룹을 염두에 두고 새 항목을 추가해야 할 때 일반적인 규칙은 다음과 같습니다.
- 사용자 설명서는 GitLab 사용에 속합니다.
- 관리 설명서는 관리 아래에 속합니다.
- 기타 설명서는 최상위 수준에 속하지만, 최상위 네비게이션을 지나치게 길게 만들지 않는 것이 중요합니다.
이러한 원칙에 따라 모든 문서 및 네비게이션 항목을 지속적으로 적용하고 있습니다.
추가할 내용
네비게이션 요소를 추가할 위치를 결정한 후 다음 단계는 무엇을 추가할 지 결정하는 것입니다. 필요한 내용의 기계적 요소는 아래에 문서화되어 있지만, 원칙적으로:
- 독자가 볼 수 있는 네비게이션 항목 텍스트는:
- 가능한 짧아야 합니다.
- 맥락에 맞아야 합니다. 부모 항목의 텍스트를 반복할 필요가 거의 없습니다.
- 널리 사용되는 것이 아니라면 전문 용어나 기술 용어를 피하세요. 예를 들어 CI는 지속적 통합의 대체어로 허용됩니다.
- 네비게이션 링크는 데이터 파일에 문서화된 규칙을 따라야 합니다.
추가할 필요가 없는 페이지
다음 페이지들을 전역 네비게이션에서 제외하세요:
- 법적 고지.
-
architecture/blueprints디렉터리의 페이지. -
user/application_security/dast/checks/디렉터리의 페이지.
다음 페이지들은 아마도 전역 네비게이션에 포함되어야 하지만 기술 작성자들이 적극적으로 작업하지는 않습니다:
-
/development디렉터리의 페이지. -
doc/administration/troubleshooting디렉터리의 지원팀이 작성한 페이지.
때때로 폐기된 기능을 위한 페이지는 폐기된 기능이 얼마나 오래되었는지에 따라 전역 네비게이션에 포함되지 않을 수 있습니다.
다른 모든 페이지는 전역 네비게이션에 포함되어야 합니다.
기술 작성팀은 전역 네비게이션에 포함되지 않은 페이지를 확인하기 위해 보고서를 실행합니다. 팀은 매달이 목록을 검토합니다.
네비게이션 구조
전역 네비게이션에는 다섯 가지 수준이 있습니다.
- 섹션
- 카테고리
- 문서
- 문서
- 문서
- 문서
- 문서
- 카테고리
이 구조를 navigation.yml 파일에서 확인할 수 있습니다.
GitLab 사용 섹션
기능 문서뿐만 아니라 GitLab 사용 섹션의 각 카테고리는 다음을 포함해야 합니다:
이렇게 하면 문서를 탐색하는 방법을 익히게 할 수 있는 반복적인 패턴이 보장됩니다.
GitLab 사용 섹션의 구조는 다음과 같습니다:
- GitLab 사용
- 최상위 페이지
- 시작하기 페이지
- 기능
- 기능
- 최상위 페이지
구성
전역 네비게이션은 두 파일에서 구성됩니다:
데이터 파일은 레이아웃에 문서에 대한 링크를 제공합니다. 레이아웃은 데이터를 컨테이너에 적절하게 스타일링하여 데이터를 구성합니다.
데이터 파일
데이터 파일은 해당 프로젝트의 네비게이션 구조를 설명합니다. 이 파일은 https://gitlab.com/gitlab-org/gitlab-docs/blob/main/content/_data/navigation.yaml에 저장되어 있으며 세 가지 주요 구성 요소로 구성됩니다.
- 섹션
- 카테고리
- 문서
섹션
각 섹션은 더 높은 수준의 네비게이션 항목을 나타냅니다. 제목과 URL로 구성됩니다:
sections:
- section_title: 텍스트
section_url: '링크'
섹션은 독자적일 수도 있고 자체 내부에 카테고리를 포함할 수도 있습니다.
카테고리
섹션 내의 각 카테고리는 네비게이션의 두 번째 수준을 구성합니다. 카테고리 제목과 링크를 포함하며 네비게이션 안에서 독립적으로 서있을 수도 있고 세 번째 수준의 하위 항목을 포함할 수도 있습니다.
독립적인 카테고리 한 개를 갖는 섹션의 예:
- section_title: 섹션 제목
section_url: '섹션-링크'
section_categories:
- category_title: 카테고리 제목
category_url: '카테고리-링크'
두 개의 독립적인 카테고리를 갖는 섹션의 예:
- section_title: 섹션 제목
section_url: '섹션-링크'
section_categories:
- category_title: 카테고리 1 제목
category_url: '카테고리-1-링크'
- category_title: 카테고리 2 제목
category_url: '카테고리-2-링크'
분명함을 위해 항상 카테고리 사이에 빈 줄을 추가하세요.
- category_title: 문서
category_url: 'category-link'
docs:
- doc_title: 문서 제목
doc_url: 'doc-link'
docs:
- doc_title: 문서 제목
doc_url: 'doc-link'
docs:
- doc_title: 문서 제목
doc_url: 'doc-link'
- category_title: Syntax
category_url: 'category-link'
docs:
- doc_title: 컴포넌트(sections, categories, and docs)
doc_url: 'doc-link'
docs:
- doc_title: 제목
doc_url: 'doc-link'
- category_title: 레이아웃 파일(로직)
category_url: 'category-link'
docs:
- doc_title: 글로벌 탐색기 빌드 및 렌더링을 위한 레이아웃 파일(layout)
doc_url: 'doc-link'
도움말