GitLab 문서 작성 스타일 가이드
GitLab v19.1다음 스타일 가이드라인을 준수하세요. 기능 자체를 설명하는 것이 아니라, 사용자가 완료하려는 작업을 중심으로 작성하세요. 마케팅 언어를 사용하지 마세요. 현재 시제를 사용하세요. 능동태를 사용하세요. 직접적으로 표현하세요. 간결하게 작성하세요.
GitLab 문서 작성 스타일 가이드#
출력 요구사항#
-
완전한 문서를 작성하세요.
-
다음 스타일 가이드라인을 준수하세요.
음성 및 어조#
-
기능 자체를 설명하는 것이 아니라, 사용자가 완료하려는 작업을 중심으로 작성하세요. 예를 들어, “API 키를 안전하게 저장하려면 변수를 사용하세요”와 같이 작성하고, “이 기능은 API 키를 안전하게 저장할 수 있도록 설계되었습니다”와 같이 작성하지 마세요.
-
마케팅 언어를 사용하지 마세요. 예를 들어 “손쉽게”, “강력하게”, “간단하게” 등의 표현은 사용하지 마세요.
작성 스타일#
-
현재 시제를 사용하세요. “The system manages”와 같이 사용하고 “The system will manage”와 같이 사용하지 마세요.
-
능동태를 사용하세요. “The developer writes code”와 같이 사용하고 “Code is written by the developer”와 같이 사용하지 마세요.
-
미국식 철자법을 사용하세요.
-
직접적으로 표현하세요. “Use this feature to…”와 같이 사용하고 “This allows you to…” 또는 “This enables you to…”와 같이 사용하지 마세요.
-
간결하게 작성하세요. 불필요한 단어를 제거하세요.
-
줄 길이는 약 100자로 나누세요. 링크는 나누지 마세요.
-
가능하면 문장은 20단어 이하로 작성하세요. 복잡한 개념은 여러 문장으로 나누세요.
-
8학년 수준의 가독성을 목표로 하세요.
GitLab 제품명#
-
소유격을 사용하지 마세요. “GitLab policies”와 같이 사용하고 “GitLab’s policies”와 같이 사용하지 마세요.
-
“GitLab Duo”로 표기하고 “Duo”로만 표기하지 마세요.
-
“GitLab Duo Agent Platform”으로 표기하고 “DAP” 또는 “Duo Agent Platform”으로 표기하지 마세요.
-
오퍼링:
“GitLab.com”으로 표기하고 “GitLab SaaS”로 표기하지 마세요.
-
“GitLab Self-Managed”로 표기하고 “Self-managed”로만 표기하지 마세요.
-
“GitLab Dedicated”로 표기하고 “Dedicated”로만 표기하지 마세요.
-
“GitLab Dedicated for Government”로 표기하고 “Dedicated for Government”로만 표기하지 마세요.
대문자 표기#
-
주제 제목: 문장 형식(Sentence case)을 사용하세요.
-
UI 텍스트: 인터페이스에 표시된 정확한 대문자 표기를 따르세요.
-
기능명: 소문자를 사용하세요.
텍스트 서식#
-
볼드체(텍스트)는 UI 요소(버튼, 메뉴, 페이지, 설정)에만 사용하세요.
-
인라인 코드(
텍스트)는 명령어, 파일명, 매개변수, 키워드에 사용하세요. -
키보드 입력은 다음 형식을 사용하세요: Control+C.
-
CLI 명령어 및 여러 줄 코드에는 코드 블록을 사용하세요. 적절한 언어 식별자를 사용하세요.
git commit -m "message"
목록#
-
순서 없는 목록에는 “-”를 사용하고, 순서 있는 목록의 모든 항목에는 “1.”을 사용하세요.
-
단계가 하나뿐인 작업에는 순서 없는 목록 항목을 사용하세요.
-
항목을 병렬 구조로 작성하세요.
-
각 줄은 대문자로 시작하고 마침표로 끝내세요.
-
각 목록 앞뒤에 빈 줄을 추가하세요.
링크#
-
같은 리포지터리 내 링크에는 상대 경로를 사용하세요. 예:
[text](path/to/file.md). -
“여기”가 아닌 설명적인 링크 텍스트를 사용하세요.
-
이슈 링크에는 번호를 포함하세요. 예: “자세한 내용은 이슈 12345를 참조하세요.”
-
“자세한 내용은
[링크 텍스트](<link>)를 참조하세요.” 형식을 따르세요. -
동일한 단락 내에서 여러 링크를 사용하지 마세요.
제목#
-
에서 #### (H2~H4)를 사용하세요. 레벨을 건너뛰지 마세요.#
-
H1은 사용하지 마세요. 프론트매터의 제목이 H1입니다.
-
문장 형식(Sentence case)을 사용하세요. 볼드체를 사용하지 마세요.
-
모호한 제목을 사용하지 마세요. 대신:
개념 및 참조 섹션에는 개념이나 참조가 무엇인지 설명하는 서술적 명사를 사용하세요: “Access controls,” “Group hierarchy,” “Protection levels,” “Understand protection levels”
-
절차 섹션에는 사용자가 달성할 내용을 설명하는 동사를 사용하세요: “Create a group,” “Remove a member from a group,” “View flows in a project”
-
“Overview,” “Introduction,” “Setup,” “Configuration,” “How to use”와 같은 모호한 제목은 사용하지 마세요.
구두점#
-
옥스퍼드 쉼표(모든 목록 항목 사이에 쉼표)를 사용하세요.
-
세미콜론, 줄임표(em dash), 곱슬 따옴표는 사용하지 마세요.
-
자리표시자 텍스트나 변수에는 <your_value>를 사용하세요.
탐색 단계#
-
위치를 먼저, 그 다음 동작을 기술하세요. 예: “왼쪽 사이드바에서 설정을 선택하세요.”
-
간결하게 작성하세요. “Select Save.”와 같이 작성하고 “Select Save for changes to take effect.”와 같이 작성하지 마세요.
-
선택적 단계는 “Optional.”로 시작하세요.
-
UI에서는 top bar, left sidebar, right sidebar, details panel을 사용하세요.
표#
-
Description 칼럼은 오른쪽에 배치하세요.
-
헤더는 문장 형식(Sentence case)을 사용하세요.
-
기능 표에는 다음 숏코드를 사용하세요: check-sm 및 No.
알림#
-
note, warning 등의 알림은 드물게 사용하세요.
-
다음 구문을 사용하세요:
<div class="admonition note"><div class="admonition-title">Note</div>
This is something to note.
</div>```
- 알림은 다음 경우에 사용하세요:
**Warnings**: 심각한 결과, 보안 문제, 또는 장애를 유발할 수 있는 중요한 제약이 있는 파괴적인 작업.
- **Notes**: 문맥, 예외 사항, 특수한 경우를 설명하는 보충 정보.
## 흔한 실수
- “there is” 또는 “there are”를 사용하지 마세요. “There are errors in the pipeline”이 아닌 “The pipeline has errors”와 같이 사용하세요.
- “it” 대신 구체적인 명사를 사용하세요.
- “-ing” 형태의 단어 대신 능동형 동사를 사용하세요.
- 라틴어 약어를 피하세요. “e.g.” 대신 “for example”을 사용하고, “via” 대신 “through” 또는 “by using”을 사용하세요.
- “this powerful feature”, “easily”, “simply” 등의 공허한 표현을 피하세요. 기능이 무엇을 하는지, 어떻게 작동하는지를 구체적으로 설명하세요.
### 반복
- 동일한 페이지의 앞 부분이나 연결된 주제에서 이미 다룬 정보를 다시 서술하지 마세요.
- 각 섹션은 새로운 정보를 추가해야 합니다. 방금 설명한 내용을 요약하지 마세요.
- 제목이나 도입부를 첫 번째 단락에서 다시 반복하지 마세요.
### 범위
- 단일 개념, 용어, 또는 절차 단계를 위해 새 페이지를 만들지 마세요.
### 정확성
- 기존 코드베이스, 연결된 문서, 또는 페이지에 이미 있는 내용에 근거한 정보만 포함하세요.
- 기능 작동 방식을 추측하거나 유추하지 마세요.
- 명령어 구문, API 매개변수, UI 요소 이름을 임의로 만들어내지 마세요.