InfoGrab DocsInfoGrab Docs

문서 스타일 가이드

요약

이 문서는 GitLab 문서의 표준을 정의합니다. 문서 스타일 가이드는 다음 페이지로 나뉩니다. GitLab 핸드북은 다음에 대한 지침을 제공합니다. 문서 스타일 가이드에 없는 지침은 다음 스타일 가이드를 따릅니다. GitLab 브랜드 가이드라인은 조직 전체에서 사용하는 보이스를 정의합니다.

이 문서는 GitLab 문서의 표준을 정의합니다.

구조#

문서 스타일 가이드는 다음 페이지로 나뉩니다.

작성#

페이지 내용
언어 GitLab 문서의 문법, 보이스, 대소문자, 단어 선택 규칙입니다.
제품, 기능 및 표준 섹션 GitLab 문서의 제품 이름과 표준 섹션 규칙입니다.
권장 단어 목록 GitLab 문서에서 권장하는 단어 선택입니다.
텍스트 및 서식 GitLab 문서의 문장부호, 줄 길이, 굵게, 코드 등 텍스트 서식 규칙입니다.
UI 요소 및 탐색 경로 GitLab 문서에서 쇼트코드로 UI 요소를 표시하는 방법입니다.

페이지 요소#

페이지 내용
이미지, 다이어그램 및 아이콘 GitLab 문서의 스크린샷, 다이어그램, 아이콘 규칙입니다.
링크 및 비디오 GitLab 문서의 링크, 링크 텍스트, 비디오, 클릭형 데모 규칙입니다.
Markdown 및 목록 GitLab 문서의 Markdown, 제목 수준, 목록 규칙입니다.
메타데이터 GitLab 문서 페이지의 프런트 매터 메타데이터입니다.
쇼트코드 및 콘텐츠 블록 GitLab 문서의 쇼트코드, 경고 상자, 탭 등 콘텐츠 블록입니다.
표 GitLab 문서에서 표를 만들고 서식을 지정하는 규칙입니다.

관련 지침#

  • 기능 상태와 버전: 제공 여부 세부 정보, 기능 플래그, 실험 및 베타 기능, 지원 중단, 업그레이드 참고 사항입니다.
  • API 및 CLI 참조: REST API, GraphQL, GitLab CLI(glab) 문서입니다.

기타 지침#

GitLab 핸드북은 다음에 대한 지침을 제공합니다.

문서 스타일 가이드에 없는 지침은 다음 스타일 가이드를 따릅니다.

GitLab 보이스#

GitLab 브랜드 가이드라인은 조직 전체에서 사용하는 보이스를 정의합니다.

이 지침을 바탕으로 GitLab 문서의 보이스는 간결하고, 직접적이며, 정확하고자 합니다. 검색하고 훑어보기 쉬운 정보를 제공하는 것이 목표입니다.

문서의 보이스는 대화하듯 자연스러우면서도 짧아야 하고, 친근하면서도 간결해야 합니다.

문서는 단일 진실 공급원(SSoT)입니다#

GitLab 문서는 구현, 사용, 문제 해결과 관련된 모든 제품 정보의 SSoT입니다. 문서는 계속 발전합니다. 새로운 제품과 기능이 추가될 때마다, 그리고 명확성, 정확성, 완결성을 높이기 위해 갱신됩니다.

이 정책은 다음과 같은 효과가 있습니다.

  • 정보 사일로를 방지하고 GitLab 제품에 대한 정보를 더 쉽게 찾을 수 있게 합니다.
  • 문서의 여러 위치에 콘텐츠를 중복해서 둘 수 없다는 뜻은 아닙니다.

주제 유형#

GitLab은 주제 유형을 사용해 제품 문서를 구성합니다.

주제 유형은 사용자가 정보를 더 빠르게 이해하도록 돕습니다. 또한 다음과 같은 문제를 해결하는 데 도움이 됩니다.

  • 콘텐츠를 찾기 어렵습니다. GitLab 문서는 방대하며 유용한 정보를 많이 담고 있습니다. 주제 유형은 반복되는 패턴을 만들어 콘텐츠를 훑어보고 파악하기 쉽게 합니다.
  • 콘텐츠가 기여자의 관점에서 작성되는 경우가 많습니다. GitLab 문서는 다양한 기여자가 작성합니다. 주제 유형(특히 작업)은 기능이 어떻게 구현되었는지를 기록하는 대신, 다른 사람을 돕는 데 맞춘 형식으로 정보를 정리하도록 돕습니다.

문서 우선 방법론#

제품 문서는 완전하고 신뢰할 수 있는 자료여야 합니다.

  • 질문의 답이 문서에 있다면 정보를 다시 풀어 쓰지 말고 문서 링크를 공유합니다.
  • GitLab 문서에 없는 정보를 발견하면 머지 리퀘스트(MR)를 만들어 문서에 그 정보를 추가합니다. 그런 다음 MR을 공유해 정보를 전달합니다.

문서에 정보를 반사적으로 더 많이 추가할수록 문서는 다른 사람이 작업을 효율적으로 수행하고 문제를 해결하는 데 더 큰 도움이 됩니다.

현지화를 위한 글쓰기#

GitLab은 글로벌 독자를 위해 글을 쓰는 데 도움이 되는 지침을 따릅니다.

GitLab 보이스는 번역을 염두에 두고 명확하고 직접적으로 쓰도록 요구합니다. 문서 스타일 가이드, 단어 목록, Vale 규칙은 문서의 일관성을 보장합니다.

문서를 다른 언어로 번역할 때는 각 단어의 의미가 분명해야 합니다. 기계 번역, GitLab Duo Chat, 기타 AI 도구의 사용이 늘어나면서 일관성은 더욱 중요해졌습니다.

다음 규칙은 문서를 더 효율적으로 번역하는 데 도움이 됩니다.

피해야 할 표현은 다음과 같습니다.

  • there is 및 there are처럼 주어를 숨기는 표현.
  • it처럼 모호한 대명사.
  • -ing로 끝나는 단어.
  • since와 because처럼 서로 혼동될 수 있는 단어.
  • e.g., i.e. 같은 라틴어 약어.
  • kill two birds with one stone처럼 특정 문화권에 한정된 표현.

사용할 표현은 다음과 같습니다.

또한 다음 지침을 염두에 둡니다.

  • 기능 이름과 기능을 조작하는 방법을 일관되게 씁니다.
  • 명사 나열을 풀어 씁니다. 예를 들어 project integration custom settings 대신 custom settings for project integrations를 사용합니다.
  • 날짜와 시간을 국제 독자를 고려해 일관되게 표기합니다.
  • 스크린샷을 포함한 삽화는 최소한으로 사용합니다.
  • UI 텍스트는 번역 시 최대 30%까지 늘어나거나 줄어드는 것을 감안합니다. 문자열이 다른 언어에서 얼마나 늘거나 줄어드는지 확인하려면 해당 문자열을 Google Translate에 붙여넣고 결과를 검토합니다. 그 언어를 하는 동료에게 번역이 명확한지 확인을 요청합니다.

표절#

출처를 밝힌 제한적인 인용이 아니라면 다른 출처의 콘텐츠를 복사해 붙여넣지 않습니다. 일반적으로 관련 정보를 자신의 말로 바꿔 쓰거나 출처로 링크하는 것이 더 좋습니다.

AI 생성 콘텐츠#

AI 도구를 사용해 문서를 생성하거나 작성을 보조할 때는 검토를 요청하기 전에 결과물을 주의 깊게 확인합니다. AI는 설득력 있게 쓰도록 설계되었지만 AI 생성 콘텐츠에는 다음과 같은 문제가 자주 나타납니다.

반복 : 페이지나 링크된 주제에서 이미 말한 내용을 다시 서술하는 콘텐츠입니다. 각 섹션은 새로운 정보를 더해야 합니다. 방금 설명한 내용을 요약하지 않습니다. 첫 문단에서 제목이나 소개를 다시 서술하지 않습니다.

모호하거나 검증할 수 없는 주장 : 코드베이스나 기존 문서에 근거하지 않은 기능 작동 방식의 설명입니다. 기존 코드베이스, 링크된 문서, 페이지에 이미 있는 콘텐츠에 근거할 수 있는 정보만 포함합니다. 기능의 작동 방식을 추측하거나 추론하지 않습니다. 명령 구문, API 매개변수, UI 요소 이름을 지어내지 않습니다.

잘못된 범위 : 적합한 페이지가 이미 있는데도 개념이나 절차를 위한 새 페이지를 만든 경우입니다. 하나의 개념, 용어, 절차 단계를 위해 새 페이지를 만들지 않습니다.

향후 버전의 기능 약속#

향후 릴리스에서 기능을 제공하겠다고 약속하지 않습니다. 예를 들어 "Support for this feature is planned."와 같은 표현은 피합니다.

향후 기능 작업은 보장할 수 없으며, 이러한 약속은 법적 문제를 일으킬 수 있습니다. 대신 이슈가 있다고 말합니다. 예를 들면 다음과 같습니다.

  • Support for improvements is proposed in [issue <issue_number>](https://work-item-link).
  • You cannot do this thing, but [issue 12345](https://work-item-link) proposes to change this behavior.

기능을 제거할 계획이라고는 말할 수 있습니다.

향후 기능을 꼭 문서화해야 한다면 면책 조항을 사용합니다.

문서 스타일 가이드

GitLab v19.6
원문 보기

요약

이 문서는 GitLab 문서의 표준을 정의합니다. 문서 스타일 가이드는 다음 페이지로 나뉩니다. GitLab 핸드북은 다음에 대한 지침을 제공합니다. 문서 스타일 가이드에 없는 지침은 다음 스타일 가이드를 따릅니다. GitLab 브랜드 가이드라인은 조직 전체에서 사용하는 보이스를 정의합니다.

이 문서는 GitLab 문서의 표준을 정의합니다.

구조#

문서 스타일 가이드는 다음 페이지로 나뉩니다.

작성#

페이지 내용
언어 GitLab 문서의 문법, 보이스, 대소문자, 단어 선택 규칙입니다.
제품, 기능 및 표준 섹션 GitLab 문서의 제품 이름과 표준 섹션 규칙입니다.
권장 단어 목록 GitLab 문서에서 권장하는 단어 선택입니다.
텍스트 및 서식 GitLab 문서의 문장부호, 줄 길이, 굵게, 코드 등 텍스트 서식 규칙입니다.
UI 요소 및 탐색 경로 GitLab 문서에서 쇼트코드로 UI 요소를 표시하는 방법입니다.

페이지 요소#

페이지 내용
이미지, 다이어그램 및 아이콘 GitLab 문서의 스크린샷, 다이어그램, 아이콘 규칙입니다.
링크 및 비디오 GitLab 문서의 링크, 링크 텍스트, 비디오, 클릭형 데모 규칙입니다.
Markdown 및 목록 GitLab 문서의 Markdown, 제목 수준, 목록 규칙입니다.
메타데이터 GitLab 문서 페이지의 프런트 매터 메타데이터입니다.
쇼트코드 및 콘텐츠 블록 GitLab 문서의 쇼트코드, 경고 상자, 탭 등 콘텐츠 블록입니다.
표 GitLab 문서에서 표를 만들고 서식을 지정하는 규칙입니다.

관련 지침#

  • 기능 상태와 버전: 제공 여부 세부 정보, 기능 플래그, 실험 및 베타 기능, 지원 중단, 업그레이드 참고 사항입니다.
  • API 및 CLI 참조: REST API, GraphQL, GitLab CLI(glab) 문서입니다.

기타 지침#

GitLab 핸드북은 다음에 대한 지침을 제공합니다.

문서 스타일 가이드에 없는 지침은 다음 스타일 가이드를 따릅니다.

GitLab 보이스#

GitLab 브랜드 가이드라인은 조직 전체에서 사용하는 보이스를 정의합니다.

이 지침을 바탕으로 GitLab 문서의 보이스는 간결하고, 직접적이며, 정확하고자 합니다. 검색하고 훑어보기 쉬운 정보를 제공하는 것이 목표입니다.

문서의 보이스는 대화하듯 자연스러우면서도 짧아야 하고, 친근하면서도 간결해야 합니다.

문서는 단일 진실 공급원(SSoT)입니다#

GitLab 문서는 구현, 사용, 문제 해결과 관련된 모든 제품 정보의 SSoT입니다. 문서는 계속 발전합니다. 새로운 제품과 기능이 추가될 때마다, 그리고 명확성, 정확성, 완결성을 높이기 위해 갱신됩니다.

이 정책은 다음과 같은 효과가 있습니다.

  • 정보 사일로를 방지하고 GitLab 제품에 대한 정보를 더 쉽게 찾을 수 있게 합니다.
  • 문서의 여러 위치에 콘텐츠를 중복해서 둘 수 없다는 뜻은 아닙니다.

주제 유형#

GitLab은 주제 유형을 사용해 제품 문서를 구성합니다.

주제 유형은 사용자가 정보를 더 빠르게 이해하도록 돕습니다. 또한 다음과 같은 문제를 해결하는 데 도움이 됩니다.

  • 콘텐츠를 찾기 어렵습니다. GitLab 문서는 방대하며 유용한 정보를 많이 담고 있습니다. 주제 유형은 반복되는 패턴을 만들어 콘텐츠를 훑어보고 파악하기 쉽게 합니다.
  • 콘텐츠가 기여자의 관점에서 작성되는 경우가 많습니다. GitLab 문서는 다양한 기여자가 작성합니다. 주제 유형(특히 작업)은 기능이 어떻게 구현되었는지를 기록하는 대신, 다른 사람을 돕는 데 맞춘 형식으로 정보를 정리하도록 돕습니다.

문서 우선 방법론#

제품 문서는 완전하고 신뢰할 수 있는 자료여야 합니다.

  • 질문의 답이 문서에 있다면 정보를 다시 풀어 쓰지 말고 문서 링크를 공유합니다.
  • GitLab 문서에 없는 정보를 발견하면 머지 리퀘스트(MR)를 만들어 문서에 그 정보를 추가합니다. 그런 다음 MR을 공유해 정보를 전달합니다.

문서에 정보를 반사적으로 더 많이 추가할수록 문서는 다른 사람이 작업을 효율적으로 수행하고 문제를 해결하는 데 더 큰 도움이 됩니다.

현지화를 위한 글쓰기#

GitLab은 글로벌 독자를 위해 글을 쓰는 데 도움이 되는 지침을 따릅니다.

GitLab 보이스는 번역을 염두에 두고 명확하고 직접적으로 쓰도록 요구합니다. 문서 스타일 가이드, 단어 목록, Vale 규칙은 문서의 일관성을 보장합니다.

문서를 다른 언어로 번역할 때는 각 단어의 의미가 분명해야 합니다. 기계 번역, GitLab Duo Chat, 기타 AI 도구의 사용이 늘어나면서 일관성은 더욱 중요해졌습니다.

다음 규칙은 문서를 더 효율적으로 번역하는 데 도움이 됩니다.

피해야 할 표현은 다음과 같습니다.

  • there is 및 there are처럼 주어를 숨기는 표현.
  • it처럼 모호한 대명사.
  • -ing로 끝나는 단어.
  • since와 because처럼 서로 혼동될 수 있는 단어.
  • e.g., i.e. 같은 라틴어 약어.
  • kill two birds with one stone처럼 특정 문화권에 한정된 표현.

사용할 표현은 다음과 같습니다.

또한 다음 지침을 염두에 둡니다.

  • 기능 이름과 기능을 조작하는 방법을 일관되게 씁니다.
  • 명사 나열을 풀어 씁니다. 예를 들어 project integration custom settings 대신 custom settings for project integrations를 사용합니다.
  • 날짜와 시간을 국제 독자를 고려해 일관되게 표기합니다.
  • 스크린샷을 포함한 삽화는 최소한으로 사용합니다.
  • UI 텍스트는 번역 시 최대 30%까지 늘어나거나 줄어드는 것을 감안합니다. 문자열이 다른 언어에서 얼마나 늘거나 줄어드는지 확인하려면 해당 문자열을 Google Translate에 붙여넣고 결과를 검토합니다. 그 언어를 하는 동료에게 번역이 명확한지 확인을 요청합니다.

표절#

출처를 밝힌 제한적인 인용이 아니라면 다른 출처의 콘텐츠를 복사해 붙여넣지 않습니다. 일반적으로 관련 정보를 자신의 말로 바꿔 쓰거나 출처로 링크하는 것이 더 좋습니다.

AI 생성 콘텐츠#

AI 도구를 사용해 문서를 생성하거나 작성을 보조할 때는 검토를 요청하기 전에 결과물을 주의 깊게 확인합니다. AI는 설득력 있게 쓰도록 설계되었지만 AI 생성 콘텐츠에는 다음과 같은 문제가 자주 나타납니다.

반복 : 페이지나 링크된 주제에서 이미 말한 내용을 다시 서술하는 콘텐츠입니다. 각 섹션은 새로운 정보를 더해야 합니다. 방금 설명한 내용을 요약하지 않습니다. 첫 문단에서 제목이나 소개를 다시 서술하지 않습니다.

모호하거나 검증할 수 없는 주장 : 코드베이스나 기존 문서에 근거하지 않은 기능 작동 방식의 설명입니다. 기존 코드베이스, 링크된 문서, 페이지에 이미 있는 콘텐츠에 근거할 수 있는 정보만 포함합니다. 기능의 작동 방식을 추측하거나 추론하지 않습니다. 명령 구문, API 매개변수, UI 요소 이름을 지어내지 않습니다.

잘못된 범위 : 적합한 페이지가 이미 있는데도 개념이나 절차를 위한 새 페이지를 만든 경우입니다. 하나의 개념, 용어, 절차 단계를 위해 새 페이지를 만들지 않습니다.

향후 버전의 기능 약속#

향후 릴리스에서 기능을 제공하겠다고 약속하지 않습니다. 예를 들어 "Support for this feature is planned."와 같은 표현은 피합니다.

향후 기능 작업은 보장할 수 없으며, 이러한 약속은 법적 문제를 일으킬 수 있습니다. 대신 이슈가 있다고 말합니다. 예를 들면 다음과 같습니다.

  • Support for improvements is proposed in [issue <issue_number>](https://work-item-link).
  • You cannot do this thing, but [issue 12345](https://work-item-link) proposes to change this behavior.

기능을 제거할 계획이라고는 말할 수 있습니다.

향후 기능을 꼭 문서화해야 한다면 면책 조항을 사용합니다.