• 스테이지 및 그룹 메타데이터
  • 예외
• 설명 메타데이터
• 전역 내비게이션에 추가되지 않도록 주의하세요
• 추가 메타데이터
• TW 메타데이터 일괄 업데이트
  • CODEOWNERS 파일 업데이트

메타데이터

매 문서의 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- 을 참조하세요.
---

/solutions 디렉토리의 문서는 다음 메타데이터를 받습니다:

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

설명 메타데이터

description 태그:

• 문서 홈페이지에 텍스트를 채우는 데 사용됩니다.
• 소셜 미디어 미리 보기에 표시됩니다.
• 검색 결과 스니펫에 사용될 수 있습니다.

Use 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 task를 사용하여 CODEOWNERS 파일을 업데이트할 수 있습니다.

CODEOWNERS 파일 업데이트

그룹 또는 TW assignments가 변경되면 CODEOWNERS 파일을 업데이트해야 합니다. 이를 위해 codeowners.rake Rake task를 실행합니다. 이 작업은 doc 디렉토리의 모든 파일을 확인하고 메타데이터를 읽어 codeowners.rake 파일의 정보를 사용하여 CODEOWNERS 파일을 채웁니다.

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

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

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

• 하나의 그룹에 여러 기술 작가를 지정하려면 작가 이름 사이에 공백을 사용하세요. 파일이 모든 작가에게 할당됩니다.

  CodeOwnerRule.new('그룹 이름', '@작가1 @작가2'),
  

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

    CodeOwnerRule.new('그룹 이름', ->(path) { path.start_with?('/doc/user') ? '@작가1' : '@작가2' }),
    

    이 예에서 작가1은 /doc/user에 관련된 파일을 위해 코드 소유자로 만듭니다. 그 외의 경우에는 작가2가 코드 소유자로 지정됩니다. 예제는 MR 127903를 참조하세요.

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

  # CodeOwnerRule.new('그룹 이름', ''),