# 튜토리얼 작성 방법

이 문서는 Nix 튜토리얼 작성을 위한 가이드입니다.

여기서 말하는 튜토리얼은 [기술 문서를 위한 Diátaxis 프레임워크](https://diataxis.fr/)에서 설명하는 *레슨*이며, 본격적으로 시작하기 전에 Diátaxis를 먼저 익혀 두기를 권장합니다. 특히 [튜토리얼과 가이드의 차이점](https://diataxis.fr/tutorials-how-to/)에 유의하십시오.

## 대상 독자

Nix 튜토리얼의 주요 대상 독자는 Linux 명령줄을 적어도 기본적으로는 다뤄 본 소프트웨어 개발자입니다.

질문에 즉시 답해 주는 전문가, 개인 맞춤형 지도와 교육, 그 밖의 도제식 학습은 Nix를 배우는 데 가장 효과적인 지원으로 알려져 있습니다. **이 튜토리얼은 그러한 지원을 전혀 받을 수 없는 사람들을 대상으로 하며**, 따라서 자기 주도 학습에 적합하도록 작성해야 합니다. 이는 여기에서 설명하는 구조를 따르면 이룰 수 있으며, 이 구조의 주된 특징은 학습자에게 생길 수 있는 모든 정보 공백을 피하고 메우는 것을 목표로 한다는 점입니다.

부수적인 효과로, 잘 작성된 튜토리얼은 대화형 교육 세션에서 강의 노트로도 활용할 수 있습니다. 따라서 부차적인 대상 독자는 Nix를 가르치는 강사입니다.

## 절차

고품질 튜토리얼을 작성하려면 작성자 본인과 다른 사람들 모두 어느 정도 시간을 들여야 합니다. 그 시간의 대부분은 대개 다음과 같은 협업에 쓰입니다.
- 올바른 접근 방식 찾기
- 설명이 학습자에게 너무 부족하지도 너무 빽빽하지도 않도록 하기
- 아이디어를 전달할 더욱 간결하고 명확한 방법을 계속 찾기

작업을 다시 하는 일이 없도록 다음 단계를 따르십시오

### 주제 선택하기

문서 팀이 튜토리얼 시리즈에 포함하기로 결정한 튜토리얼을 모아 둔 [추적 이슈](https://github.com/NixOS/nix.dev/issues/572)가 있습니다. 잘 알고 있거나 특별히 관심 있는 주제를 다루는 이슈를 선택하십시오.

다른 사람이 이미 시작한 작업과 중복되지 않도록 참조된 이슈와 풀 리퀘스트를 확인하십시오.

개요에 담긴 것보다 더 많은 [튜토리얼 요청](https://github.com/NixOS/nix.dev/issues?q=is%3Aopen+is%3Aissue+label%3Atutorial)이 있습니다. 작업하려는 주제가 어디에서도 추적되고 있지 않다면 [새 이슈를 여십시오](https://github.com/NixOS/nix.dev/issues/new?&template=tutorial.md). 이는 작성자에게는 목표를 명확히 할 기회이고, 다른 모든 사람에게는 그 주제에 관심이 있다는 것을 알게 되는 기회입니다.

### 개요를 담아 풀 리퀘스트 제출하기

[권장 구조](#structure)에 따라 작성한 튜토리얼 개요를 담아 풀 리퀘스트를 제출하십시오. 개요에는 각 섹션의 내용을 글머리 기호로 정리해야 합니다. 튜토리얼 작업 중임을 알릴 수 있도록 풀 리퀘스트 설명에서 추적 이슈를 참조하십시오.

리뷰를 거치면 학습 목표와 기술적 구현 측면에서 올바른 방향으로 가고 있는지 확인할 수 있습니다.

### 개요 확장하기

작성한 개요와 [](style-guide)에 따라 튜토리얼 내용을 자세히 작성하십시오.

리뷰를 거치면 학습자에게 부담을 주지 않으면서 필요한 모든 정보를 올바른 순서로 담을 수 있습니다.

### 리뷰 코멘트 반영하기

상세한 피드백을 바탕으로 튜토리얼을 수정하십시오. 친구나 동료와 함께 튜토리얼을 테스트해 보기를 권장합니다. 이렇게 하면 암묵적인 전제 조건을 드러내는 데 도움이 될 뿐만 아니라 읽는 데 걸리는 시간도 현실적으로 추정할 수 있습니다.

최종 검토에서는 모든 내용이 기술적으로 올바른지 확인합니다.

## 구조

각 튜토리얼은 다음 질문에 답해야 합니다.

또한 학습 자료를 설계하기 위한 가이드로 [How Learning Works (요약)](https://www.lesswrong.com/posts/mAdMkFqWzbJRB544m/book-review-how-learning-works) 책을 적극 추천합니다.

### 무엇을 배우게 됩니까?

문제 정의와 학습 목표를 기술하십시오.

튜토리얼의 학습 목표는 언제나 기술을 습득하는 것이며, 기술은 반복되는 패턴을 지닌 여러 상황에 적용할 수 있다는 점에서 구별됩니다.

### 무엇이 필요합니까?

필요한 사전 지식과 기술을 명시하십시오. 튜토리얼은 명시된 전제 조건만으로 학습 목표를 달성하기에 충분하도록 항상 작성되어야 합니다.

예시:

- 이전 장으로의 링크
- 특정 분야의 기술이나 지식

### 얼마나 걸립니까?

읽는 데 걸리는 시간을 추정하십시오. 이는 학습자가 계획된 작업을 완수할 여력이 있는지 확인하고, 그럼으로써 Nix 생태계로의 여정을 계속하지 못하게 만들 수 있는 좌절을 피하는 데 중요합니다.

추정치는 학습자의 기존 지식과 숙련도에 따라 달라집니다. 선택적인 기술이나 지식이 읽는 시간에 어떤 영향을 줄 수 있는지 적어 둘 수 있습니다.

### 무엇을 해야 합니까?

학습 목표를 달성하기 위한 단계를 제공하십시오. 이 단계들은 원하는 결과로 반복해서 이어지는 직접적인 지시 형태여야 합니다.

`:::{dropdown}` 블록 안에 맥락 설명을 추가하는 것도 좋습니다. 이렇게 하면 주의를 흐트러뜨리는 요소를 최소화하면서 이해를 도울 수 있습니다.

### 무엇을 배웠습니까?

연습 문제나 풀이 예제, 그 밖의 자기 평가 수단을 제공하십시오.

이곳은 튜토리얼을 계속 개선할 수 있도록 독자에게 피드백을 주거나 저자에게 질문할 방법을 안내하기에도 좋은 곳입니다.

### 다음 단계

사용 사례가 얼마나 잘 다루어졌는지에 따라 독자에게 다음을 안내하십시오.

- 참조 매뉴얼
- 가이드 또는 기타 튜토리얼
- 요약을 곁들인 검증된 외부 자료 링크
- 사용 가능한 지원 도구의 개요와 각 도구의 성숙도 및 유지 관리 상태
- 아이디어의 개요와 커뮤니티 논의 현황

실용적인 학습 자료와 이론적인 학습 자료를 명확히 구분할 것을 권장합니다. 그러면 독자가 당장 일을 처리할지, 아니면 더 깊이 배울지를 빠르게 결정할 수 있습니다.

외부 자료에는 독자가 무엇을 기대할 수 있는지 알 수 있도록 요약을 붙여야 하며, 가능하면 읽는 데 걸리는 시간도 포함하는 것이 좋습니다. 블로그 게시물은 링크에 원래 제목을 사용하고 `(<author>, <year>)`를 덧붙여야 합니다. 이렇게 하면 저자의 공로를 밝히고, 독자에게 정보가 얼마나 최신인지 알려 줄 수 있습니다.