언어
GitLab v19.6요약
GitLab 문서는 명확하고 이해하기 쉬워야 합니다. 대부분의 경우 수동태보다 능동태를 사용하면 텍스트를 이해하고 번역하기가 더 쉽습니다. GitLab이 주어이면 어색할 때가 있습니다. GitLab이 만든 것이 아니라 GitLab이 고객에게 제공하는 기능과 이점에 집중합니다.
GitLab 문서는 명확하고 이해하기 쉬워야 합니다.
- 불필요한 단어를 피합니다.
- 명확하고 간결하게 쓰며, 주제의 목표에 집중합니다.
- 미국식 문법을 따르는 미국 영어로 작성합니다. (
British.yml에서 검사합니다.)
능동태#
대부분의 경우 수동태보다 능동태를 사용하면 텍스트를 이해하고 번역하기가 더 쉽습니다.
예를 들어 다음과 같이 씁니다.
- The developer writes code for the application.
다음과 같이 쓰지 않습니다.
- Application code is written by the developer.
GitLab이 주어이면 어색할 때가 있습니다. 예를 들어 GitLab exports the report가 그렇습니다.
이런 경우에는 수동태를 대신 사용합니다. 예: The report is exported.
고객 관점#
GitLab이 만든 것이 아니라 GitLab이 고객에게 제공하는 기능과 이점에 집중합니다.
예를 들어 다음과 같이 씁니다.
- Use merge requests to compare code in the source and target branches.
다음과 같이 쓰지 않습니다.
- GitLab allows you to compare code.
- GitLab created the ability to let you compare code.
- Merge requests let you compare code.
고객 관점에서 쓰지 않았음을 나타내는 단어는 allow와 enable입니다. 대신 you를 사용해 사용자에게 직접 말하듯이 씁니다.
신뢰 구축#
제품 문서는 영업이나 마케팅 문구를 덧붙이지 않고 명확하고 간결한 정보를 제공하는 데 집중해야 합니다.
- easily나 simply 같은 단어를 사용하지 않습니다.
- "This feature will save you time and money."와 같은 마케팅 문구를 사용하지 않습니다.
대신 사실과 달성할 수 있는 목표에 집중합니다. 구체적으로 씁니다. 예:
- The build time can decrease when you use this feature.
- Use this feature to save time when you create a project. The API creates the file and you do not have to manually intervene.
의인화#
소프트웨어, 시스템, 데이터에 인식, 의도, 자각 같은 사람의 특성을 부여하지 않습니다.
시스템이 무엇을 경험하거나 의도하는지가 아니라 기계적으로 무엇을 하는지를 설명합니다.
다음과 같이 씁니다.
- The field is removed before the response reaches the agent.
- A
reason:is set on every error when the cause can be determined. - The command prompts for confirmation before it displays the key.
- This setting configures the runner to deploy your website.
- The following commands require a directory of output files.
- The Planner Agent supports GitLab planning concepts, including work item hierarchies.
- The agent parses natural language inputs.
- The agent infers user intent from the provided context.
다음과 같이 쓰지 않습니다.
- The field is removed before the agent sees the response.
- A
reason:is set on every error when the tool knows why it failed. - The command asks for confirmation before it displays the key.
- This setting tells the runner to deploy your website.
- The following commands assume that you have a directory of output files.
- The Planner Agent understands GitLab planning concepts, including work item hierarchies.
- The agent understands natural language.
- The agent understands what the user is trying to accomplish.
시스템이나 구성 요소에 요구 사항이 있을 때는 "needs"가 아니라 "requires" 또는 "must"를 사용합니다. 요구 사항은 버전, 설정, 파일 위치와 같이 고정된 조건입니다. "Needs"는 사람이 부족하게 여기거나 원하는 것을 나타냅니다.
다음과 같이 씁니다.
- The runner requires a registration token.
- The cache requires a directory to store its files in.
- The backup file must be owned by the
gituser.
다음과 같이 쓰지 않습니다.
- The runner needs a registration token.
- The cache needs a directory to store its files in.
- The backup file needs to be owned by the
gituser.
Anthropomorphism.yml에서 검사합니다.
자기 지시적 글쓰기#
문서 자체에 대해 쓰지 않습니다. 예를 들어 다음과 같은 표현을 사용하지 않습니다.
- This page shows...
- This guide explains...
이러한 표현은 사용자의 읽는 속도를 늦춥니다. 대신 바로 요점으로 들어갑니다. 예를 들어 다음과 같이 쓰는 대신
- This page explains different types of pipelines.
다음과 같이 씁니다.
- GitLab has different types of pipelines to help address your development needs.
SelfReferential.yml에서 검사합니다.
대소문자#
GitLab은 회사로서 소문자를 선호하는 경향이 있습니다.
주제 제목#
주제 제목에는 문장형 대소문자(sentence case)를 사용합니다. 예:
# Use variables to configure pipelines## Use the To-Do List
기능 이름#
기능 이름은 소문자로 씁니다.
다만 드물게 기능 이름을 제목형 대소문자(title case)로 쓸 수 있습니다. 예외는 다음과 같습니다.
- 모든 문서에 일관되게 적용되도록 markdownlint에 고유 명칭으로 추가된 경우
- 단어 목록에 추가된 경우
용어가 단어 목록에 없으면 GitLab 테크니컬 라이터에게 문의합니다. 기능 이름을 정하고 GitLab 표준을 충족하는지 확인하는 데 도움이 필요하면 핸드북을 참고합니다.
기능 페이지나
features.yml에 있는
용어나 문구의 대소문자를 기본적으로 따라 쓰지 않습니다.
기타 용어#
다음 이름은 대문자로 시작합니다.
- GitLab 제품 티어. 예: GitLab Free, GitLab Ultimate.
- 서드파티 조직, 소프트웨어, 제품. 예: Prometheus, Kubernetes, Git, The Linux Foundation.
- 방법 또는 방법론. 예: Continuous Integration, Continuous Deployment, Scrum, Agile.
해당 대상의 공식 출처에 나열된 대소문자 스타일을 따릅니다. 비표준 대소문자 스타일일 수도 있습니다. 예: GitLab, npm.
가상 사용자 정보#
문서에 실제 사용자 이름이나 이메일 주소를 포함하지 않습니다.
텍스트의 경우:
Sidney Jones,Zhang Wei,Alex Garcia처럼 다양하거나 성별 구분이 없는 이름에 흔한 성을 조합해 사용합니다.- 가상 이메일 주소는
example.com으로 끝나도록 만듭니다.
스크린샷의 경우:
-
스크린샷을 찍기 전에 페이지를 임시로 편집합니다.
- 변경할 텍스트를 마우스 오른쪽 버튼으로 클릭합니다.
- Inspect를 선택합니다.
- Elements 대화 상자에서 실제 사용자 정보가 포함된 텍스트를 예시 데이터로 바꾸도록 HTML을 편집합니다.
- 대화 상자를 닫습니다. 웹 페이지의 모든 사용자 데이터가 입력한 예시 데이터로 바뀌어 있어야 합니다.
- 스크린샷을 찍습니다.
-
또는 테스트 환경에 예시 계정을 만들어 그곳에서 스크린샷을 찍습니다.
-
환경을 재현할 수 없으면 macOS의 Preview 같은 이미지 편집 도구로 사용자 데이터를 흐리게 처리합니다.
가상 URL#
문서에 예시 URL을 포함할 때는 다음을 사용합니다.
- 도메인 이름이 일반적인 경우
example.com - GitLab Self-Managed만 가리킬 때
gitlab.example.com. GitLab.com에는gitlab.com을 사용합니다.
가상 토큰#
문서에 실제 토큰을 사용하지 않습니다.
예시에는 다음 가상 토큰을 사용합니다.
| 토큰 유형 | 토큰 값 |
|---|---|
| 개인 액세스 토큰 | <your_access_token> |
| 애플리케이션 ID | 2fcb195768c39e9a94cec2c2e32c59c0aad7a3365c10892e8116b5d83d4096b6 |
| 애플리케이션 시크릿 | 04f294d1eaca42b8692017b426d53bbc8fe75f827734f0260710b83a556082df |
| CI/CD 변수 | Li8j-mLUVA3eZYjPfd_H |
| 프로젝트 러너 토큰 | yrnZW46BrtBFqM7xDzE7dddd |
| 인스턴스 러너 토큰 | 6Vk7ZsosqQyfreAxXTZr |
| 트리거 토큰 | be20d8dcc028677c931e04f3871a9b |
| 웹훅 시크릿 토큰 | 6XhDroRcYPM5by_h-HLY |
| 상태 확인 토큰 | Tu7BgjR9qeZTEyRzGG2P |
축약형#
특히 튜토리얼, 안내 문서, 사용자 인터페이스에서는 축약형을 사용하도록 권장하며, 친근하고 격식 없는 어조를 만들 수 있습니다.
다만 일부 축약형은 피해야 합니다.
| 축약형을 사용하지 않는 경우 | 예시 | 대신 사용 |
|---|---|---|
| 고유 명사와 동사를 함께 쓰는 경우 | Terraform's a helpful tool. | Terraform is a helpful tool. |
| 부정을 강조하는 경우 | Don't install X with Y. | Do not install X with Y. |
| 참조 문서에서 | Don't set a limit. | Do not set a limit. |
| 오류 메시지에서 | Requests to localhost aren't allowed. | Requests to localhost are not allowed. |
소유격#
조직이나 제품 이름 같은 고유 명사에는 소유격('s)을 사용하지 않습니다.
예를 들어 Docker's CLI 대신 the Docker CLI를 사용합니다.
전치사#
필요하면 문장 끝에 전치사를 사용합니다. 문장 끝에 남은 전치사도 괜찮습니다. 예:
- You can leave the group you're a member of.
- Share the credentials with users you want to give access to.
다음과 같은 구성은 위 문장보다 격식 없는 어조에 가깝습니다.
- You can leave the group of which you're a member.
- Share the credentials with users to which you want to give access.
약어#
약어를 사용하면 페이지에서 처음 사용할 때 풀어 씁니다. 한 페이지에서 두 번 이상 풀어 쓰지 않습니다.
- 제목: 특히 널리 쓰이지 않는 약어는 주제 제목에서 피합니다.
- 복수형: 약어를 복수형으로 만들지 않도록 합니다. 예를 들어
YAMLs가 아니라YAML files를 사용합니다. 약어를 복수형으로 만들어야 한다면 아포스트로피를 사용하지 않습니다. 예를 들어API's가 아니라APIs를 사용합니다. - 소유격: 약어를 소유격으로 만들 때는 주의합니다. 가능하면 약어를 소유격으로 만들지 않도록 문장을 씁니다. 약어를 소유격으로 만들어야 한다면 단어를 풀어 쓰는 것을 고려합니다.
숫자#
텍스트의 숫자는 0부터 9까지는 단어로 풀어 쓰고 10 이상은 숫자를 사용합니다.
UI의 숫자는 Pajamas를 참고합니다.
날짜와 시간#
날짜는 month day, year 형식을 사용하고, 시간은 AM과 PM을 사용합니다.
예:
January 3, 2026 at 10:30 AM
UI의 날짜와 시간은 Pajamas를 참고합니다.