글로벌 내비게이션(글로벌 내비)은 문서에서 가장 왼쪽에 있는 창입니다. 글로벌 내비로 콘텐츠를 탐색할 수 있습니다.

조사에 따르면 사용자는 Google로 GitLab 제품 문서를 검색합니다. 검색 결과로 들어왔을 때 읽고 있는 콘텐츠와 관련된 주변 주제를 찾을 수 있어야 합니다. 글로벌 내비가 이 정보를 제공합니다.

가장 상위 수준에서 글로벌 내비는 워크플로 기반입니다. 내비게이션은 사용자가 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 등)의 문서 콘텐츠를 모아 구성합니다.

테크니컬 라이터의 동의 없이 글로벌 내비에 항목을 추가하지 않습니다.

글로벌 내비게이션에 주제를 추가하는 방법은 다음과 같습니다.

1. 해당 주제가 https://docs.gitlab.com에 게시되어 있는지 확인합니다.
2. navigation.yaml 파일에 항목을 추가합니다.
3. 리뷰와 머지를 위해 MR을 테크니컬 라이터에게 할당합니다.

추가 위치#

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

• GitLab 사용자. Reporter부터 Owner까지 모든 수준의 권한을 가진 사용자가 GitLab을 일상적으로 사용하기 위한 문서입니다.
• GitLab 관리자. 주로 GitLab을 호스팅하는 기반 인프라에 접근해야 하는 GitLab Self-Managed 인스턴스용 문서입니다.
• 기타 문서. 고객이 GitLab을 일상적으로 사용하는 범위를 벗어난 문서와 기여자를 위한 문서가 여기에 포함됩니다. 다른 그룹에 맞지 않는 문서도 여기에 속합니다.

이 그룹을 염두에 두고, 새 항목을 어디에 추가할지에 대한 일반 규칙은 다음과 같습니다.

• 사용자 문서는 Use GitLab에 속합니다.
• 관리 문서는 Administer 아래에 속합니다. 이러한 문서에는 다음을 언급하는 절이 자주 포함됩니다.
  • gitlab.rb 또는 gitlab.yml 파일 변경.
  • rails 콘솔 접근 또는 Rake 작업 실행.
  • Admin 영역에서 수행하는 작업.
  • 인스턴스 관리자만 수행할 수 있는 작업.
• 구독 및 청구 문서는 Subscribe 아래에 속합니다. 플랜과 티어, 구독 관리, 좌석과 청구 계정, 일반적인 GitLab Credits 개념에 관한 페이지가 여기에 포함됩니다. 특정 기능이 GitLab Credits를 어떻게 소비하는지에 관한 페이지는 해당 기능의 섹션 아래에 추가합니다.
• 기타 문서는 최상위에 속하지만, 최상위 내비게이션이 지나치게 길어지면 그 목적을 잃으므로 주의해야 합니다.

모든 문서와 내비게이션 항목이 이 원칙을 따르도록 하는 작업은 단계적으로 진행 중입니다.

추가할 내용#

내비게이션 요소를 어디에 추가할지 정했다면, 다음 단계는 무엇을 추가할지 정하는 것입니다. 필요한 구체적인 방법은 아래에 설명되어 있으며, 원칙은 다음과 같습니다.

• 내비게이션 항목 텍스트(독자가 보는 문구)는 다음과 같아야 합니다.
  • 가능한 한 짧아야 합니다.
  • 컨텍스트에 맞아야 합니다. 상위 항목의 텍스트를 반복할 필요는 거의 없습니다.
  • 널리 쓰이는 표현이 아니라면 전문 용어나 업계 용어를 피합니다. 예를 들어 CI는 Continuous Integration을 대체해도 무방합니다.
• 내비게이션 링크는 데이터 파일에 문서화된 규칙을 따라야 합니다.

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

다음 페이지는 글로벌 내비에서 제외합니다.

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

다음 페이지는 글로벌 내비에 있는 편이 좋지만, 테크니컬 라이터가 적극적으로 추가하지는 않습니다.

• /development 디렉터리의 페이지.
• 지원 팀이 작성한 페이지로, doc/administration/troubleshooting 디렉터리에 있는 문서.

기능 페이지를 글로벌 내비게이션에서 제외해야 할 때도 있습니다. 예를 들어 지원이 중단된 기능의 페이지는 중단 시점에 따라 글로벌 내비에 포함되지 않을 수 있습니다. 이러한 페이지가 의도적으로 글로벌 내비게이션에서 제외되었음을 분명히 하려면 페이지 front matter에 다음 코드를 추가합니다.

ignore_in_report: true

그 밖의 모든 페이지는 글로벌 내비에 있어야 합니다.

누락된 페이지 확인#

테크니컬 라이팅 팀은 내비에 없는 페이지를 파악하기 위해 보고서를 실행합니다. 팀은 이 목록을 매달 검토합니다.

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

기본적으로 이 보고서는 /development 디렉터리의 페이지도 건너뛰지만, 필요하면 INCLUDE_DEV 플래그를 지정해 이 페이지를 포함할 수 있습니다.

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

Use GitLab 섹션#

Use GitLab 섹션의 각 범주에는 기능 문서 외에 다음이 포함되어야 합니다.

• 최상위 페이지.
• Get started 페이지.

이렇게 하면 사용자가 문서를 탐색하는 방식에 익숙해지도록 반복 가능한 패턴이 만들어집니다.

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

• Use GitLab
  • 최상위 페이지
    • Get started 페이지
    • 기능
    • 기능

구성#

글로벌 내비는 다음 두 파일로 만들어집니다.

• 데이터
• 레이아웃

데이터 파일은 문서로 향하는 링크를 레이아웃에 공급합니다. 레이아웃은 적절히 스타일이 지정된 컨테이너에 맞춰 내비 안에 데이터를 배치합니다.

데이터 파일#

데이터 파일은 해당 프로젝트의 내비게이션 구조를 기술합니다. 이 파일은 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 링크가 동시에 두 개 생기는 일을 막을 수 있습니다.

문법#

모든 구성 요소에서 들여쓰기와 다음 문법 규칙을 지킵니다.

제목#

• 기능 이름의 첫 글자를 대문자로 하는 문장형 대소문자를 사용합니다.
• 특수 문자가 없다면 제목을 따옴표로 감쌀 필요는 없습니다. 예를 들어 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 는 데이터 파일을 공급받아 글로벌 내비를 만듭니다.

글로벌 내비에는 여섯 개 업스트림 프로젝트의 링크가 모두 들어 있습니다. 글로벌 내비 URL은 변경하는 문서 파일에 따라 접두사가 다릅니다.

CSS 클래스#

내비는 공통 main.css 파일에서 스타일을 지정합니다. 스타일을 변경할 때는 팀 내 개발이 수월하도록 스타일을 한곳에 모아 둡니다.

테스트#

navigation.yaml에 대해서는 check-navigation.sh에서 여러 검사를 실행하며, 이 스크립트는 YAML 파일이 갱신될 때 파이프라인 job으로 실행됩니다.