Task 토픽은 절차를 완료하는 방법을 안내합니다.

형식#

Task 토픽은 다음 형식을 따릅니다:

title: Title (starts with an active verb, like "Create a widget" or "Delete a widget")
---

Do this task when you want to...

Task result (optional)

Prerequisites (optional):

- Thing 1
- Thing 2
- Thing 3

To do this task:

1. Location then action. (Go to this menu, then select this item.)
1. Another step.
1. Another step.

Next steps (optional).

예시는 다음과 같습니다.

title: Create an issue
---

Create an issue when you want to track bugs or future work.

Prerequisites:

- The Developer, Maintainer, or Owner role for the project.

To create an issue:

1. On the top bar, select **Search or go to** and find your project.
1. In the left sidebar, select **Plan** > **Work items**.
1. In the upper-right corner, select **New item**.
1. From the **Type** dropdown list, select **Issue** if it is not already selected.
1. Enter a title and description. If you have reference content that lists each field, link to it here.
1. Select **Create issue**.

To view the issue, filter the **Work items** list by **Type** = **Issue** and select your issue.

Task 토픽 제목#

제목 텍스트에는 active verb + noun 구조를 사용합니다. 예를 들어 Create an issue입니다.

Task에 단계가 하나뿐인 경우#

단계가 하나뿐인 task를 작성해야 한다면 그 단계를 순서 없는 목록 항목으로 만듭니다. 이 형식은 목록 규칙과의 일관성을 유지하면서 해당 단계를 눈에 띄게 합니다.

예를 들면 다음과 같습니다:

title: Create a merge request
---

To create a merge request:

- In the upper-right corner, select **New merge request**.

Task를 수행하는 방법이 둘 이상 있는 경우#

UI에서 task를 수행하는 방법이 둘 이상 있다면 주된 방법 하나만 문서화합니다.

다만 여러 방법을 문서화해야 하는 경우도 있습니다. 그런 경우에는 다음과 같이 작성합니다:

• task를 평소대로 소개합니다. 그런 다음 task를 수행하는 방법마다 토픽 제목을 추가합니다.
• 토픽 제목은 task 토픽 제목보다 한 단계 아래에 둡니다.
• 가능성이 가장 높은 방법을 먼저 두어 내림차순으로 task를 나열합니다.
• task 제목은 최대한 간결하게 작성합니다. 가능하다면 infinitive + noun을 사용합니다.

예시는 다음과 같습니다.

title: Change the default branch name
---

You can change the default branch name for the instance or group.
If the name is set for the instance, you can override it for a group.

## For the instance

Prerequisites:

- Administrator access.

To change the default branch name for an instance:

1. Step.
1. Step.

## For the group

Prerequisites:

- The Developer, Maintainer, or Owner role for the group.

To change the default branch name for a group:

1. Step.
1. Step.

UI와 API에서 task 수행#

UI에서 수행하는 것과 같은 task를 수행할 수 있는 API가 있는 경우가 많습니다.

그런 경우에는 다음과 같이 작성합니다:

• API로 연결되는 한 문장짜리 링크에 별도의 제목을 두지 않습니다.

• Use GitLab 문서에는 API 예시를 넣지 않습니다. API 예시는 API 문서에 두어야 합니다. GraphQL 예시가 있다면 API 문서는 언젠가 옮겨질 수 있으므로 별도의 페이지에 둡니다.

• 필요하지 않다면 API를 언급하지 않습니다. 사용자는 API 문서를 검색할 수 있고, 불필요한 링크는 문서를 어수선하게 만듭니다.

• API를 꼭 언급해야 한다는 의견이 강하다면 UI task 마지막에 다음 문장을 추가합니다:

  To create an issue, you can also [use the API](link.md).

Task 소개#

task 토픽을 시작할 때는 active verb + noun 구조를 사용하고 해당 동작에 관한 컨텍스트를 제공합니다. 예를 들어 Create an issue when you want to track bugs or future work입니다.

task 단계를 시작할 때는 간결한 동작 뒤에 콜론을 붙입니다. 예를 들어 To create an issue:입니다.

Task 사전 요구 사항#

task를 수행하는 데 Guest 외의 권한이 필요하다면 해당하는 모든 권한을 사전 요구 사항에 나열합니다. 각 권한을 어떤 표현으로 쓰는지는 단어 목록을 참고합니다. 해당하는 권한을 먼저 나열합니다.

관리자만 수행할 수 있는 task라면 사전 요구 사항에 Administrator access.를 넣습니다.

Prerequisites는 항목이 하나뿐이더라도 항상 복수형으로 씁니다.

사전 요구 사항에는 구독이나 애드온을 나열하지 않습니다. 이러한 내용은 제품 가용성 세부 정보에만 포함합니다.

한 페이지의 여러 task가 사전 요구 사항을 공유한다면 제목이 Prerequisites인 별도의 토픽을 만들 수 있습니다.

사전 요구 사항 문장 작성#

사전 요구 사항을 작성할 때는 가능한 한 다음 패턴을 따릅니다.

• You must have:라는 도입부가 생략되었다고 가정하고 명사 목록을 사용합니다.
• You must:라는 도입부가 생략되었다고 가정하고 동사 목록을 사용합니다.

예를 들어 명사 목록은 다음과 같습니다:

Prerequisites:

- The Maintainer or Owner role for the project.
- A project access token.
- Docker installed locally.

동사 목록은 다음과 같습니다:

Prerequisites:

- Enable Cloud Logging API on your Google Cloud project.
- Configure dependency scanning on your target projects.
- Create a service account with appropriate permissions.

Ensure that나 You must have 같은 표현은 피합니다.

관련 주제#

• task 단계 작성 방법
• 적용 전후 예시