메타데이터

각 문서 Markdown 페이지는 YAML 프론트 매터를 포함합니다.
메타데이터의 모든 값은 문자열로 취급되며 문서 웹사이트에서만 사용됩니다.

단계 및 그룹 메타데이터

각 페이지는 그 페이지가 속한 단계와 그룹에 대한 메타데이터는 물론 정보 블록을 포함해야 합니다. 예를 들면:

---
stage: 예시 단계
group: 예시 그룹
info: 이 페이지와 관련된 단계/그룹에 배정된 기술 작가를 확인하려면 https://handbook.gitlab.com/handbook/product/ux/technical-writing/#assignments 를 참조하세요.
---

메타데이터를 채우려면 다음 정보를 포함하세요:

  • stage: 페이지의 대부분 내용이 속하는 단계.

  • group: 페이지의 대부분 내용이 속하는 그룹.

  • info: 페이지의 단계 및 그룹과 관련된 기술 작가를 찾는 방법.

예외

/development 디렉토리의 문서에는 다음 메타데이터가 포함됩니다:

---
stage: 예시 단계
group: 예시 그룹
info: Maintainer 역할을 가진 모든 사용자는 이 내용에 대한 업데이트를 병합할 수 있습니다. 자세한 내용은 https://docs.gitlab.com/ee/development/development_processes.html#development-guidelines-review 을 참조하세요.
---

/solutions 디렉토리의 문서에는 다음 메타데이터가 포함됩니다:

---
stage: 솔루션 아키텍처
group: 솔루션 아키텍처
info: 이 페이지는 솔루션 아키텍처 팀이 소유합니다.
---

설명 메타데이터

description 태그:

  • 문서 홈 페이지의 텍스트를 채우는 데 사용됩니다.

  • 소셜 미디어 미리 보기에서 표시됩니다.

  • 검색 결과 스니펫에 사용될 수 있습니다.

최상위 페이지(예: GitLab 사용하기 및 그 아래 계층)에서 설명은 명사의 목록입니다. 예를 들어, 조직 설정하기의 설명은 사용자, 그룹, 네임스페이스, SSH 키.입니다.

다른 페이지의 경우 설명은 적극적으로 유지되지 않습니다. 그러나 추가하고 싶다면 페이지의 내용에 대한 짧은 설명을 사용하세요.
Google의 양질의 메타 설명을 작성하기 위한 모범 사례에서 팁을 참고하세요.

페이지가 전역 탐색에 추가되지 않도록 하기

특정 페이지가 전역 탐색에 추가되지 않도록 하려면 (navigation.yaml에 항목이 추가되지 않도록) 페이지 메타데이터에 다음을 추가하세요:

ignore_in_report: true

이 메타데이터가 페이지에 설정되면:

  • pages_not_in_nav.js 스크립트가 문서를 처리할 때 페이지를 무시합니다.

  • 기술 작가들이 기술 작문 팀의 월간 작업을 수행할 때 페이지를 전역 탐색에 추가하라는 메시지를 받지 않습니다.

추가 메타데이터

다음 메타데이터는 선택적이며 적극적으로 유지되지 않습니다.

  • feedback: “도움 및 피드백” 바닥글을 포함하지 않으려면 false로 설정하세요.

  • noindex: 페이지가 검색 엔진에 의해 인덱싱되지 않도록 하려면 false로 설정하세요.

  • redirect_to: 리디렉션을 제어하는 데 사용됩니다. 자세한 내용은 GitLab 문서에서의 리디렉션을 참조하세요.

  • searchbar: 페이지 헤더에 검색 바를 포함하지 않으려면 false로 설정하세요.

  • toc: “이 페이지에서” 탐색을 포함하지 않으려면 false로 설정하세요.

TW 메타데이터 일괄 업데이트

CODEOWNERS 파일에는 파일 목록과 관련된 기술 작가들이 포함되어 있습니다.

병합 요청에 문서가 포함된 경우, CODEOWNERS 파일의 정보는 다음을 결정합니다:

  • 승인자 섹션의 사용자 목록.
  • GitLab Bot이 커뮤니티 기여자를 위한 기술 작가에게 알리는 대상.

Rake 작업을 사용하여 CODEOWNERS 파일을 업데이트할 수 있습니다.

CODEOWNERS 파일 업데이트

그룹이나 TW 할당이 변경되면, CODEOWNERS 파일을 업데이트해야 합니다. 이를 위해 codeowners.rake Rake 작업을 실행합니다. 이 작업은 doc 디렉터리의 모든 파일을 확인하고, 메타데이터를 읽으며, CODEOWNERS 파일을 채우기 위해 codeowners.rake 파일의 정보를 사용합니다.

CODEOWNERS 파일을 업데이트하려면:

  1. 필요에 따라 영향을 받는 doc 페이지의 단계 및 그룹 메타데이터를 업데이트하세요. 변경 사항이 많을 경우, 이 단계를 별도의 MR에서 수행할 수 있습니다.
  2. 변경 사항으로 codeowners.rake 파일을 업데이트하세요.
  3. gitlab 리포지토리의 루트로 이동하세요.
  4. 다음 명령어로 Rake 작업을 실행하세요: bundle exec rake tw:codeowners
  5. CODEOWNERS 파일의 변경 사항을 검토하세요.
  6. 모든 변경 사항을 추가하고 커밋한 다음, 브랜치를 origin으로 푸시하세요.
  7. 병합 요청을 생성하고 검토를 위해 기술 작성 관리자에게 할당하세요.

codeowners.rake 파일을 업데이트할 때:

  • 단일 그룹에 대해 여러 작가를 지정하려면, 작가 이름 사이에 공백을 사용하세요. 파일은 두 작가 모두에게 할당됩니다.

    CodeOwnerRule.new('Group Name', '@writer1 @writer2'),

    • 그룹 내에서 서로 다른 작가를 서로 다른 디렉터리의 문서에 할당하려면, path 매개변수를 사용해 디렉터리를 지정하세요:

      CodeOwnerRule.new('Group Name', ->(path) { path.start_with?('/doc/user') ? '@writer1' : '@writer2' }),

      이 예에서 writer1은 /doc/user에 있는 이 그룹 관련 파일의 코드 소유자입니다. 모든 다른 경우에는 writer2가 코드 소유자가 됩니다. 예시로 MR 127903을 참조하세요.

  • 할당된 작가가 없는 그룹은, 파일에 그룹 이름을 포함하고 해당 줄을 주석 처리하세요:

    # CodeOwnerRule.new('Group Name', ''),