자습서 페이지 유형
자습서는 복잡한 워크플로 또는 시나리오의 end-to-end walkthrough을 포함하는 페이지입니다. 일반적으로 자습서를 사용하는 경우:
- 해당 워크플로에는 각 단계가 하위 단계로 이루어진 연속적인 단계들이 필요합니다.
- 단계는 다양한 GitLab 기능이나 타사 도구를 다룹니다.
자습서 가이드
- 자습서는 작업(task.md)이 아닙니다. 작업은 한 가지 절차에 대한 지시를 제공합니다. 자습서는 특정 목표를 달성하기 위해 여러 작업을 결합시킵니다.
- 자습서는 작동하는 예제를 제공합니다. 이상적으로 독자는 자습서에서 설명하는 예제를 생성할 수 있어야 합니다. 정확하게 복제할 수 없더라도 비슷한 것을 복제할 수 있어야 합니다.
- 자습서는 새로운 기능을 소개하지 않습니다.
- 자습서는 진실의 단일 진실 공급원(Single Source of Truth) 원칙을 준수할 필요가 없습니다. 다른 곳에서 이미 사용 가능한 콘텐츠를 복제하는 것은 이상적이지 않지만, 독자가 필요한 정보를 얻기 위해 페이지를 떠나도록 하는 것보다 나쁩니다.
자습서 파일 이름과 위치
자습서 마크다운 파일의 경우 다음 중 하나를 선택할 수 있습니다:
- 제품 설명서가 있는 디렉터리에 파일을 저장합니다.
-
doc/tutorials아래에 서브폴더를 만들고 파일 이름을index.md로 지정합니다.
왼쪽 내비게이션에 자습서를 관련 기능 설명 파일과 가까운 위치에 추가합니다.
한 자습서 페이지 중 하나에 자습서 링크를 추가합니다.
자습서 형식
자습서는 다음과 같은 형식을 사용해야 합니다:
# 제목 (예: "자습서: 웹사이트 만들기"와 같이 "Tutorial:"로 시작하는 동사)
자습서가 수행하는 작업과 예상되는 결과를 설명하는 문단입니다.
웹사이트를 만들려면:
1. [첫 번째 작업 수행](#do-the-first-task)
1. [두 번째 작업 수행](#do-the-second-task)
## 시작하기 전에
이 섹션은 선택 사항입니다.
- 사항 1
- 사항 2
- 사항 3
## 첫 번째 작업 수행
단계 1 수행 방법:
1. 첫 번째 단계.
1. 다른 단계.
1. 다른 단계.
## 두 번째 작업 수행
시작하기 전에, [첫 번째 작업을 수행했는지 확인하세요](#do-the-first-task).
단계 2 수행 방법:
1. 첫 번째 단계.
1. 다른 단계.
1. 다른 단계.
이 형식을 준수하는 자습서 예시는 다음과 같습니다: 자습서: 첫 번째 Git 커밋 만들기.
자습서 페이지 제목
페이지 제목은 자습서:로 시작하고 자습서: 웹사이트 만들기와 같이 동사로 끝나는 형식을 사용합니다.
왼쪽 내비게이션에서 전체 페이지 제목을 사용합니다. 줄임표시는 하지 마십시오.
파이프라인이 성공하도록 텍스트를 따옴표로 묶어주세요. 예: "자습서: 첫 번째 Git 커밋 만들기".
자습서로 GitLab 배우기 페이지에서는 제목에 자습서를 사용하지 마십시오.
스크린샷
자습서에 중요한 단계를 설명하기 위해 스크린샷을 포함할 수 있습니다. 핵심 제품 설명서에서는 스크린샷을 삼가하십시오. 그러나 자습서에서는 스크린샷이 복잡한 프로세스에서 사용자가 어디에 있는지 이해하는 데 도움이 될 수 있습니다.
자습서에서 스크린샷의 수를 균형 있게 유지하여 이야기의 흐름을 방해하지 않도록 해야 합니다. 예를 들어, 자습서 중간에 큰 스크린샷을 하나 넣지 마십시오. 대신 여러 개의 작은 스크린샷을 여기저기에 넣으세요.
자습서 어조
다른 주제 유형보다 더 친근한 어조를 사용하십시오. 예를 들어,
- 작업 후에 격려나 축하의 단어를 추가할 수 있습니다.
- 때때로 미래 시제를 사용하여 단계를 소개할 수 있습니다. 예:
다음에는 이슈를 에픽과 연결할 예정입니다. - 조금 더 상호작용하는 어조를 사용할 수 있습니다. 예:
이 작업은 시간이 걸릴 수 있습니다.
메타데이터
자습서인 페이지에는 파일 상단에 가장 적절한 stage:와 group: 메타데이터를 추가하세요.
대부분의 콘텐츠가 단일 그룹과 일치하지 않는 경우, 단계에 none을 지정하고 그룹에 Tutorials을 지정하세요:
stage: none
group: Tutorials
도움말