글로벌 내비게이션(global nav)은 문서의 가장 왼쪽 패널입니다. 글로벌 내비게이션을 사용하여 콘텐츠를 탐색할 수 있습니다.

연구에 따르면 사용자들은 GitLab 제품 문서를 검색할 때 Google을 사용합니다. 검색 결과 페이지에 도달했을 때, 사용자가 읽고 있는 콘텐츠와 관련된 주변 주제를 찾을 수 있도록 하는 것이 목표입니다. 글로벌 내비게이션은 이러한 정보를 제공합니다.

최상위 수준에서 글로벌 내비게이션은 워크플로 기반입니다. 내비게이션은 사용자가 GitLab 사용 방법에 대한 정신적 모델을 구축하는 데 도움이 되어야 합니다. 각 상위 워크플로 기반 주제 아래의 레벨은 기능의 이름입니다. 예를 들면 다음과 같습니다:

Use GitLab (워크플로) > Build your application (워크플로) > Get started (기능) > CI/CD (기능) > Pipelines (기능)

일부 오래된 내비게이션 섹션은 알파벳 순으로 되어 있지만, 내비게이션은 기본적으로 워크플로 기반이어야 합니다.

내비게이션 항목이 없으면:

• 페이지를 열 때 내비게이션이 닫히고, 독자는 현재 위치를 잃게 됩니다.

• 다른 페이지들과 함께 그룹에서 페이지를 볼 수 없습니다.

내비게이션 항목에 적합한 단어 선택#

왼쪽 내비게이션에 항목을 추가하기 전에 사용할 품사를 선택하세요.

내비게이션 항목은 페이지 제목과 일치해야 합니다. 그러나 제목이 너무 길 경우 문구를 줄일 때 다음 중 하나를 사용하세요:

• Merge requests와 같은 명사.

• Install GitLab 또는 Get started with runners와 같은 능동형 동사.

페이지의 목적을 명확하게 나타내는 문구를 사용하세요. 예를 들어 Get started는 Get started with runners만큼 도움이 되지 않습니다.

내비게이션 항목 추가#

글로벌 내비게이션은 gitlab-org/technical-writing/docs-gitlab-com 프로젝트의 data/en-us/navigation.yaml 파일에 저장되어 있습니다. docs.gitlab.com의 문서 사이트는 Hugo를 사용하여 구축되며, 여러 프로젝트(charts, gitlab, gitlab-runner, omnibus-gitlab 등)의 문서 콘텐츠를 조합합니다.

Technical Writer의 동의 없이 글로벌 내비게이션에 항목을 추가하지 마세요.

글로벌 내비게이션에 주제를 추가하려면:

• https://docs.gitlab.com에 해당 주제가 게시되어 있는지 확인합니다.

• navigation.yaml 파일에 항목을 추가합니다.

• 검토 및 병합을 위해 Technical Writer에게 MR을 할당합니다.

추가 위치#

문서 페이지는 다음 그룹에 속한다고 볼 수 있습니다:

• GitLab 사용자. 이 문서는 Reporter부터 Owner까지 어떤 권한 수준의 사용자도 GitLab을 일상적으로 사용하기 위한 것입니다.

• GitLab 관리자. 이는 주로 GitLab을 호스팅하는 기반 인프라에 대한 액세스가 필요한 GitLab Self-Managed 인스턴스를 위한 문서입니다.

• 기타 문서. 여기에는 일상적인 GitLab 사용 이외의 고객과 기여자를 위한 문서가 포함됩니다. 다른 그룹에 맞지 않는 문서는 여기에 속합니다.

이러한 그룹을 염두에 두고, 다음은 새 항목을 추가할 위치에 대한 일반적인 규칙입니다.

• 사용자 문서는 Use GitLab에 속합니다.

• 관리 문서는 Administer 아래에 속합니다. 이 문서에는 종종 다음 내용을 언급하는 섹션이 포함됩니다:

gitlab.rb 또는 gitlab.yml 파일 변경.

• Rails 콘솔 액세스 또는 Rake 작업 실행.

• Admin 영역에서 작업 수행.

• 인스턴스 관리자만 수행할 수 있는 작업.

• 기타 문서는 최상위 수준에 속하지만, 최상위 내비게이션이 지나치게 길어지지 않도록 주의해야 합니다. 너무 길면 내비게이션의 목적을 달성하지 못합니다.

모든 문서 및 내비게이션 항목이 이러한 원칙을 준수하도록 하는 작업이 점진적으로 진행 중입니다.

추가할 내용#

내비게이션 요소를 추가할 위치를 결정한 후, 다음 단계는 추가할 내용을 결정하는 것입니다. 필요한 내용의 세부 사항은 아래에 문서화되어 있지만, 원칙적으로:

• 내비게이션 항목 텍스트(독자가 보는 텍스트)는:

가능한 한 짧아야 합니다.

• 맥락에 맞아야 합니다. 상위 항목의 텍스트를 반복할 필요는 거의 없습니다.

• 광범위하게 사용되는 경우를 제외하고, 전문 용어나 은어를 피하세요. 예를 들어 CI는 Continuous Integration의 허용 가능한 대체어입니다.

• 내비게이션 링크는 데이터 파일에 문서화된 규칙을 따라야 합니다.

추가하지 않아도 되는 페이지#

다음 페이지는 글로벌 내비게이션에서 제외하세요:

• 법적 고지.

• user/application_security/dast/checks/ 디렉터리의 페이지.

다음 페이지는 글로벌 내비게이션에 포함되어야 하지만, Technical Writer가 적극적으로 추가하지 않습니다:

• /development 디렉터리의 페이지.

• 지원 팀이 작성한 페이지로, doc/administration/troubleshooting 디렉터리 아래에 있습니다.

때로는 기능 페이지를 글로벌 내비게이션에서 제외해야 할 수 있습니다. 예를 들어, 더 이상 사용되지 않는 기능의 페이지는 기능이 deprecated된 시점에 따라 글로벌 내비게이션에 없을 수 있습니다. 이러한 페이지가 의도적으로 글로벌 내비게이션에서 제외되었음을 명확히 하려면, 페이지의 front matter에 다음 코드를 추가하세요:

ignore_in_report: true

다른 모든 페이지는 글로벌 내비게이션에 있어야 합니다.

누락된 페이지 확인#

Technical Writing 팀은 보고서를 실행하여 내비게이션에 없는 페이지를 확인합니다. 팀은 이 목록을 매월 검토합니다.

이 보고서는 front matter에 ignore_in_report: true가 있는 페이지를 건너뜁니다.

기본적으로 이 보고서는 /development 디렉터리의 페이지도 건너뛰지만, 필요한 경우 INCLUDE_DEV 플래그를 사용하여 이러한 페이지를 포함하도록 실행할 수 있습니다:

make check-pages-not-in-nav INCLUDE_DEV=true

Use GitLab 섹션#

기능 문서 외에도 Use GitLab 섹션의 각 카테고리에는 다음이 포함되어야 합니다:

• 최상위 페이지.

• 시작하기 페이지.

이를 통해 사용자가 문서를 탐색하는 방법에 익숙해질 수 있는 반복 가능한 패턴이 보장됩니다.

Use GitLab 섹션의 구조는 다음과 같습니다:

• Use GitLab

최상위 페이지

시작하기 페이지

• 기능

• 기능

구성#

글로벌 내비게이션은 두 개의 파일로 구성됩니다:

• 데이터

• 레이아웃

데이터 파일은 문서 링크를 레이아웃에 제공합니다. 레이아웃은 데이터를 적절히 스타일이 지정된 내비게이션 컨테이너 안에 구성합니다.

데이터 파일#

데이터 파일은 해당 프로젝트의 내비게이션 구조를 설명합니다. https://gitlab.com/gitlab-org/technical-writing/docs-gitlab-com/-/blob/main/data/en-us/navigation.yaml에 저장되어 있습니다.

각 항목은 세 가지 주요 구성 요소로 이루어집니다:

• title

• url

• submenu (선택 사항)

예를 들면:

- title: Getting started
  url: 'user/get_started/'
- title: Tutorials
  url: 'tutorials/'
  submenu:
    - title: Find your way around GitLab
      url: 'tutorials/gitlab_navigation/'
      submenu:
        - title: 'Tutorial: Navigate the GitLab interface'
          url: 'tutorials/left_sidebar/'

각 항목은 독립적으로 사용하거나 submenu 아래에 중첩된 페이지를 포함할 수 있습니다. 새 구성 요소는 두 칸씩 들여씁니다.

모든 내비게이션 링크:

• 선택 가능해야 합니다.

• 고유한 페이지를 참조해야 합니다.

• 페이지의 앵커를 가리켜서는 안 됩니다. 예: path/to/page/#anchor-link.

이 규칙을 따라야 중복 링크나 동시에 두 개의 .active 링크가 생기지 않습니다.

문법#

모든 구성 요소에 대해 들여쓰기를 준수하고 다음 문법 규칙을 따르세요.

제목#

• 기능 이름을 대문자로 표기하는 문장 형식(sentence case)을 사용하세요.

• 특수 문자가 있는 경우를 제외하고는 제목을 따옴표로 감쌀 필요가 없습니다. 예를 들어 GitLab CI/CD에는 /가 있으므로 따옴표로 감싸야 합니다. 관례적으로 제목을 큰따옴표로 감싸세요: title: "GitLab CI/CD".

URL#

URL은 상대 경로여야 합니다. 추가로:

• 각 URL 끝에 슬래시 /를 붙이세요(.html 또는 .md가 아님).

• 상대 링크를 앞쪽 슬래시 /로 시작하지 마세요.

• 웹사이트에서 보이는 경로와 일치시키세요.

• 관례적으로 항상 URL을 작은따옴표로 감싸세요: 'url'. 글로벌 내비게이션 링크를 찾으려면 전체 URL에서 https://docs.gitlab.com/을 제거하세요.

• 외부 URL에 링크하지 마세요. 왼쪽 내비게이션을 클릭하여 문서 사이트를 벗어나는 것은 혼란스러운 사용자 경험입니다.

상대 URL 예시:

레이아웃 파일 (로직)#

내비게이션 Vue.js 컴포넌트 sidebar_menu.vue는 데이터 파일을 입력받아 글로벌 내비게이션을 구축합니다.

글로벌 내비게이션에는 6개의 업스트림 프로젝트의 링크가 포함됩니다. 글로벌 내비게이션 URL은 변경하는 문서 파일에 따라 다른 접두사를 가집니다.

CSS 클래스#

내비게이션은 일반적인 main.css 파일에서 스타일이 지정됩니다. 스타일을 변경하려면 팀 내 더 나은 개발을 위해 그룹으로 유지하세요.

테스트#

check-navigation.sh에서 navigation.yaml에 대한 다양한 검사를 실행하며, YAML 파일이 업데이트될 때 파이프라인 job으로 실행됩니다.