Wagtail Documentation
문서 작성¶
Wagtail 문서는 정보 전달의 네 가지 모드로 작성됩니다. 각 정보 전달 유형은 목적이 있으며 특정 대상을 목표로 합니다.
우리는 Daniele Procida의 Diátaxis 문서 프레임워크를 따르고 있습니다.
작성 모드 선택하기¶
Wagtail 문서의 각 페이지는 단일 정보 전달 모드로 작성되어야 합니다. 여러 모드가 혼합된 단일 페이지는 이해하기 더 어렵습니다. 정보 전달 유형이 혼합된 문서가 있다면, 이를 분리하는 것이 가장 좋습니다. 각 문서의 첫 번째 섹션에 링크를 추가하여 동일한 주제에 대한 다른 문서를 상호 참조하세요.
특정 모드로 문서를 작성하면 사용자가 원하는 것을 이해하고 빠르게 찾는 데 도움이 됩니다.
튜토리얼¶
튜토리얼은 새로운 사용자가 특정 주제를 통해 안내받을 수 있도록 설계된 학습 지향 리소스입니다. 효과적인 학습을 돕기 위해 튜토리얼은 다루는 주제를 설명하는 예제를 제공해야 합니다.
튜토리얼이 반드시 모범 사례를 따르는 것은 아닙니다. 시작하기 쉽게 만들기 위해 설계되었습니다. 튜토리얼은 구체적이고 특정합니다. 반복 가능해야 하고, 자신감을 심어주며, 모든 학습자에게 매번 성공적인 결과를 가져와야 합니다.
해야 할 일¶
대화체 언어 사용하기
축약형을 사용하고, 1인칭 복수로 말하며, 안심시키는 어조를 사용하세요. 예: “우리는 이것을 할 것입니다.”
사람들이 올바른 방향으로 가고 있음을 안심시키기 위해 그림이나 코드의 구체적인 결과물을 사용하세요. 예: “새로운 로그인 페이지는 다음과 같아야 합니다:” 또는 “이제 여러분의 디렉토리에는 세 개의 파일이 있어야 합니다”.
하지 말아야 할 일¶
사람들에게 무엇을 배울 것인지 말하지 마세요. 대신, 어떤 작업을 완료할 것인지 말해주세요.
튜토리얼에서 선택 사항을 사용하지 마세요. ‘만약(if)’이라는 단어는 위험 신호입니다! 예: “만약 이것을 하고 싶다면…” 예상되는 행동과 결과는 모호하지 않아야 합니다.
학습자가 주제에 대한 사전 이해가 있다고 가정하지 마세요.
방법 안내¶
가이드는 주어진 작업을 가장 잘 수행하는 방법에 대한 조언을 제공합니다. 방법 안내는 명확한 목표나 목적을 가진 작업 지향적입니다.
해야 할 일¶
가이드 이름을 잘 지으세요 - 학습자가 가이드가 정확히 무엇을 하는지 이해할 수 있도록 하세요.
행동과 결과에 집중하세요. 예: “X를 하면, Y가 일어나야 합니다.”
학습자가 일반적인 개념에 대한 기본적 이해가 있다고 가정하세요.
독자에게 추가 자료를 안내하세요.
하지 말아야 할 일¶
불필요하게 엄격한 어조를 사용하지 마세요. 예: “절대 X를 해서는 안 됩니다.”
참조¶
참조 자료는 정보 지향적입니다. 참조는 잘 구조화되어 있으며 독자가 특정 주제에 대한 정보를 찾을 수 있도록 합니다. 짧고 간결해야 합니다. 지루해도 괜찮습니다! 명령형 어조를 사용하세요. 예: “Page 모델을 상속하세요”.
대부분의 참조는 Python 코드의 doc-string을 기반으로 자동 생성됩니다.
설명¶
설명은 이해 지향적입니다. 설명은 높은 수준이며 개념과 디자인 결정에 대한 맥락을 제공합니다. 설명에는 코드가 거의 또는 전혀 포함되지 않으며, 실제 초안에 대한 이론적 이해를 심화시키는 데 사용됩니다. 설명은 연결을 설정하는 데 사용되며, 탐구되는 원칙에 대한 사전 지식이 필요할 수 있습니다.