문서화 프레임워크#
저희는 문서를 네 가지 범주로 나누는 기술 문서를 위한 Diátaxis 프레임워크에 따라 문서를 작성하는 것을 목표로 합니다:
기여자들이 이 범주들 사이의 차이를 이해하는 데 어려움을 겪는다는 것을 알게 되었습니다. Diátaxis 프레임워크를 읽어 보실 것을 강력히 권장하지만, 각 범주를 다음과 같이 요약할 수 있습니다:
참조#
참조 자료는 다음과 같아야 합니다
어떤 함수, 클래스 등이 존재하는지 단순히 나열하며 “무엇이 있는지”에 집중합니다
간결한 언어를 사용하고, 텍스트와 레이아웃을 훑어보기와 임의 접근에 최적화합니다
관련성 있고 완전한 사용 예시를 보여 줍니다
더 쉽게 찾을 수 있도록 관련 항목에 링크합니다
튜토리얼#
튜토리얼은 사용자에게 특정 활동을 단계별로 안내하여 생태계에서 흔히 쓰이는 도구와 패턴을 가르칩니다. 활동 자체도 중요하지만, 독자가 배운 다른 내용들을 서로 연결해 주는 것도 목표입니다.
튜토리얼의 구조는 학습자의 인지 부담을 최소화해야 하며, 선택지와 사용자 실수의 여지를 적극적으로 없애야 합니다.
가이드#
가이드는 특정 목표를 달성하거나 특정 문제를 해결하는 방법을 보여 주는 단계의 목록입니다. 목표는 독자가 근본적인 이론이나 더 넓은 맥락을 이해하도록 돕는 것이 아니라, 특정한 결과에 도달하도록 돕는 것입니다.
가이드는 독자가 다루는 주제를 이해할 배경지식을 이미 갖추고 있다고 가정하므로, 새로운 개념이 나올 때마다 이를 소개하며 설명할 필요가 없습니다.
개념#
개념은 코드의 내부 동작을 설명하거나, 생태계의 특정 아이디어나 요소를 어떻게 바라보아야 하는지를 설명합니다. 개념은 어떤 것이 오늘날과 같은 방식으로 동작하게 된 역사적 배경을 설명할 수도 있습니다.
어떤 것이 동작하는 방식을 세세한 부분까지 쓰고 싶어진다면, 아마도 설명 문서를 작성하려는 것입니다.
가이드와 튜토리얼 비교#
기여자들은 주로 가이드와 튜토리얼의 차이를 어려워한다는 것을 알게 되었습니다.
차이를 이해하는 데 도움이 되는 몇 가지 설명을 소개합니다.
가이드는 독자가 어떤 결과를 얻기 위한 일련의 지침만을 원하는 “작업” 맥락에서 사용됩니다.
이 맥락에서 독자는 이 지침이 어떻게 또는 왜 동작하는지 이미 알고 있거나 관심이 없을 수 있으며, 원하는 결과를 얻으려면 무엇을 해야 하는지만 알고 싶어 합니다.
튜토리얼은 독자가 특정 작업을 수행하는 연습을 하기 위해 일련의 지침을 따라가는 “학습” 맥락에서 사용됩니다.
이 맥락에서는 독자가 이미 배웠을 수 있는 다른 내용들과 연결할 수 있도록 약간의 동기 부여나 설명이 도움이 되지만, 초점은 어떻게나 왜가 아니라 활동 자체에 있습니다.
두 가지 다른 상황에서 비행기를 착륙시키는 것에 빗대어 보면 이해하기 쉽습니다.
조종사가 의식을 잃어서, 이제 추락하지 않으려면 여러분이 직접 비행기를 착륙시켜야 한다고 가정해 봅시다. 이런 상황에서는 그저 죽지 않는 방법만 알고 싶을 것입니다. 어떻게, 왜 그런지에는 관심이 없고 그저 무사히 땅에 내려서고 싶을 뿐입니다. 이것이 가이드가 필요한 상황입니다.
비행 시뮬레이터에서 훈련 중인 조종사는 비행기 착륙을 연습하고 싶어 합니다. 훈련생 조종사는 언제 착륙 장치를 내리고 언제 플랩을 조정해야 하는지 등을 판단하는 연습이 필요합니다. 비행 시뮬레이션 중에 실제로 비행기를 착륙시키는 것보다 성공적인 착륙을 이루는 개별 기술을 익히는 것이 더 중요합니다. 이것이 튜토리얼이 필요한 상황입니다.
마지막으로, how-to 가이드와 튜토리얼의 차이는 다음과 같이 생각해 볼 수도 있습니다.
가이드: “1단계: 이것을 하십시오, 2단계: 저것을 하십시오, 등등”
튜토리얼: “이것을 어떻게 하는지 보여 드릴 테니 제 손을 잡으십시오”