튜토리얼 작성 방법

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

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

대상 독자

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

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

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

절차

고품질 튜토리얼을 작성하려면 작성자 본인과 다른 사람들 모두 어느 정도 시간을 들여야 합니다. 그 시간의 대부분은 대개 다음과 같은 협업에 쓰입니다.

• 올바른 접근 방식 찾기

• 설명이 학습자에게 너무 부족하지도 너무 빽빽하지도 않도록 하기

• 아이디어를 전달할 더욱 간결하고 명확한 방법을 계속 찾기

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

주제 선택하기

문서 팀이 튜토리얼 시리즈에 포함하기로 결정한 튜토리얼을 모아 둔 추적 이슈가 있습니다. 잘 알고 있거나 특별히 관심 있는 주제를 다루는 이슈를 선택하십시오.

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

개요에 담긴 것보다 더 많은 튜토리얼 요청이 있습니다. 작업하려는 주제가 어디에서도 추적되고 있지 않다면 새 이슈를 여십시오. 이는 작성자에게는 목표를 명확히 할 기회이고, 다른 모든 사람에게는 그 주제에 관심이 있다는 것을 알게 되는 기회입니다.

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

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

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

개요 확장하기

작성한 개요와 스타일 가이드에 따라 튜토리얼 내용을 자세히 작성하십시오.

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

리뷰 코멘트 반영하기

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

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

구조

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

또한 학습 자료를 설계하기 위한 가이드로 How Learning Works (요약) 책을 적극 추천합니다.

무엇을 배우게 됩니까?

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

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

무엇이 필요합니까?

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

예시:

• 이전 장으로의 링크

• 특정 분야의 기술이나 지식

얼마나 걸립니까?

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

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

무엇을 해야 합니까?

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

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

무엇을 배웠습니까?

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

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

다음 단계

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

• 참조 매뉴얼

• 가이드 또는 기타 튜토리얼

• 요약을 곁들인 검증된 외부 자료 링크

• 사용 가능한 지원 도구의 개요와 각 도구의 성숙도 및 유지 관리 상태

• 아이디어의 개요와 커뮤니티 논의 현황

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

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