튜토리얼 스타일 가이드라인

TON 문서를 위한 튜토리얼을 작성하기로 결정하셨나요?

기여자로 함께하게 되어 기쁩니다! 튜토리얼이 TON Docs의 기존 콘텐츠 스타일과 품질을 따르도록 하기 위해 아래 가이드라인을 검토해 주세요.

튜토리얼의 구조와 제목을 어떻게 사용해야 하는지 익숙해지는 데 시간을 할애하는 것이 중요합니다. 기존 튜토리얼을 읽어보고 이전 Pull Requests 를 확인한 후에 자신의 튜토리얼을 제출해 주세요.

프로세스

중요

작성을 시작하기 전에 아래 가이드라인을 읽어보세요! 검토 프로세스를 훨씬 빠르게 진행할 수 있는 표준화와 품질 수준을 보장하는 데 도움이 될 것입니다.

또한, 우리가 제공한 샘플 튜토리얼 구조를 반드시 참조하세요.

1. 시작하려면 GitHub에서 ton-docs 리포지토리를 포크한 다음 복제하고 로컬 리포지토리에 새 브랜치를 만드세요.
2. 품질과 가독성을 염두에 두고 튜토리얼을 작성하세요! 기존 튜토리얼을 살펴보고 무엇을 목표로 해야 하는지 알아보세요.
3. 검토를 위해 제출할 준비가 되면 지점에서 Pull Request를 열고 제출하세요. 우리에게 알림이 전송되면 검토 절차가 시작됩니다:
   1. 튜토리얼의 최종 초안을 제출하혀고 노력해 주세요. 몇 가지 오타와 문법 수정은 허용되지만, 튜토리얼을 게시하기 전에 큰 변경이 필요한 경우, 리뷰와 수정에 훨씬 더 많은 시간이 걸릴 것입니다.
4. 제출하신 내용을 검토하고 필요한 모든 변경을 완료하면, Pull Request를 병합하고 TON Documentation에 튜토리얼을 게시할 것입니다. 그 후 곧 연락을 드리고 결제를 준비하겠습니다!
5. 게시되면 소셜 미디어에서 튜토리얼을 홍보하는 것을 잊지 마세요! 문서 관리자들은 여러분이 우리와 협력하는 한 이러한 홍보를 확대하는 데 도움을 줄 수 있습니다.

요약하면 워크플로우는 다음과 같습니다:

1. ton-docs 리포지토리를 포크하고 복제합니다.
2. 튜토리얼을 작성 및 수정합니다.
3. 검토를 위해 Pull Request를 제출합니다.
4. 필요한 모든 변경 사항을 적용합니다.
5. 튜토리얼이 병합되고 게시됩니다.
6. 소셜 미디어에서 튜토리얼을 홍보합니다!

문맥

"THE"를 "TON" 앞에 추가하는 주된 문제는 TON 문서화 및 편집 정책을 개발하는 동안 마케팅, 공급업체, 개발자 등 다양한 부서가 "Blockchain," "Ecosystem" 등과 같은 단어를 "TON"과 결합하여 단일 시스템, 네트워크, 브랜드의 강력한 이미지를 만들기 위해 토론에 참여했다는 것입니다. 긴 토론 끝에 강력한 브랜드 이미지를 위해 "THE" 없이 작성할 수 있고 대문자로 작성할 수 있는 단어와 구문의 용어집을 작성하기로 결론지었습니다. 현재 두 가지 단어 조합이 있습니다: TON Blockchain 및 TON Ecosystem.

TON Connect, TON SDK, TON Grants 등 다른 TON 모듈 이름의 경우, 문맥에 따라 다릅니다. 대문자 규칙을 적용하지만 관사 규칙에는 유연합니다. 구성 요소 이름이 단독으로 사용될 때는 관사 없이 사용하는 것이 좋습니다. 그러나 TON Connect 프로토콜과 같이 일반 명사와 결합된 경우에는 엔티티 프로토콜을 지칭하므로 관사가 필요합니다.

"TON + 명사" (예: "the TON world," "the TON community" 등)와 같은 다른 단어 조합의 경우, 우리는 명사와 결합할 때 기사를 기대하기 때문에 관사의 사용을 제한하지 않습니다.

일반 팁

• 기존 콘텐츠를 복사하여 붙여넣지 마세요. 표절은 심각한 문제이며 용납되지 않습니다. 튜토리얼이 기존 콘텐츠에서 영감을 얻은 경우, 이를 참조하고 링크를 추가하세요. 다른 튜토리얼/리소스에 링크할 때는 가급적 TON Docs 리소스를 사용하세요.
• 안내 동영상 또는 동영상 콘텐츠를 Google Drive에 업로드하여 PR에 포함하세요.
• 어떤 계정에서, 어디서, 왜 자금을 조달하는지를 포함하여 계정 자금 조달에 대해 명확하게 설명해야 합니다. 학습자가 이 작업을 스스로 수행할 수 있다고 가정하지 마세요!
• 학습자가 예상되는 내용을 이해하는 데 도움이 되도록 터미널 스니펫 또는 스크린샷 형태로 샘플 출력을 표시합니다. 긴 출력을 다듬어 주세요.
• 학습자에게 오류를 디버깅하는 방법을 가르치기 위해 일부러 오류를 발생시키는 오류 중심 접근 방식을 취하세요. 예를 들어, 컨트랙트를 배포하기 위해 계정에 자금을 지원해야 하는 경우 먼저 자금을 지원하지 않고 배포를 시도하고 반환되는 오류를 관찰한 다음 (계정에 자금을 지원하여) 오류를 수정하고 다시 시도하세요.
• 잠재적인 오류와 및 문제 해결 방법을 추가하세요. 물론 튜토리얼에 가능한 모든 오류를 나열할 필요는 없지만, 중요하거나 가장 일반적인 오류를 파악하기 위해 노력해야 합니다.
• 클라이언트 측에서는 React 또는 Vue를 사용하세요.
• PR을 만들기 전에 먼저 코드를 직접 실행하여 명백한 오류를 방지하고 예상대로 작동하는지 확인하세요.
• 튜토리얼 간의 다른 소스로 연결되는 외부/교차 링크를 포함하지 마세요. 튜토리얼이 길다면, 더 긴 과정이나 경로로 전환하는 방법에 대해 논의할 수 있습니다.
• 필요한 경우 복잡한 과정을 설명하기 위해 사진 또는 스크린샷을 제공하세요.
• Learn-tutorials 리포지토리의 'static' 디렉터리에 업로드하세요 - 외부 사이트에 대한 핫링크는 이미지가 손상될 수 있으므로 사용하지 마세요.
• **이미지 링크는 markdown 형식이어야 하며, 리포지토리에 있는 static 디렉토리의 raw GitHub URL만 사용해야 합니다. ![이미지 이름](https://raw.githubusercontent.com/ton-community/ton-docs/main/static/img/tutorials/<your image filename>.png?raw=true)
  • URL 끝에 ?raw=true를 추가하는 것을 잊지 마세요.

튜토리얼을 구성하는 방법

샘플 튜토리얼 구조

직접 확인하시려면 샘플 튜토리얼 구조를 살펴보세요.

• 제목은 튜토리얼의 목표를 요약하여 직접적이고 명확하게 작성해야 합니다. 튜토리얼 제목을 문서 내부의 제목으로 추가하지 말고 markdown 문서 파일명을 사용하세요.
  • 예를 들어: 튜토리얼의 제목이 "Step by step guide for writing your first smart contract in FunC"인 경우 파일 이름은 다음과 같아야 합니다:
    'step-by-step-guide-for-writing-your-first-smart-contract-in-func.md'와 같은 형식이어야 합니다.
• 이 튜토리얼이 왜 중요한지, 튜토리얼의 맥락이 무엇인지 설명하는 소개 섹션을 포함하세요. 당연하다고 생각하지 마세요.
• 선행 지식, 완료해야 할 기존 튜토리얼, 필요한 토큰 등을 설명하는 사전 요구 사항 섹션을 포함하세요.
• 튜토리얼을 시작하기 전에 설치해야 하며 튜토리얼에서 다루지 않는 기술(예: TON 지갑 확장 프로그램, Node.js 등)을 설명하는 요구사항 섹션을 포함하세요. 튜토리얼 중에 설치될 패키지를 나열하지 마세요.
• 소제목(H2: ##) 을 사용하여 튜토리얼 본문 내에서 설명을 세분화할 수 있습니다. 소제목을 사용할 때는 목차를 염두에 두고 일관성을 유지하세요.
  • 소제목 아래의 내용이 짧은 경우(예: 단락 하나와 코드 블록 하나) 소제목 대신 굵은 텍스트를 사용하는 것이 좋습니다.
• 배운 내용을 요약하고 주요 포인트를 강화하며 튜토리얼 완료를 축하하는 결론 섹션을 포함하세요.
• (선택 사항) 좋은 후속 튜토리얼이나 기타 리소스(프로젝트, 기사 등) 로 연결되는 다음 단계 섹션을 포함하세요.
• (선택사항) 튜토리얼의 마지막에 저자 소개 섹션을 포함하세요. 귀하의 GitHub 프로필(이름, 웹사이트 등 포함) 링크와 Telegram 프로필 링크를 포함하세요(사용자가 도움과 질문을 위해 연락하거나 태그할 수 있도록).
• 이 튜토리얼을 작성하는 데 다른 문서, GitHub 리포지토리 또는 기타 튜토리얼에서 도움을 받았다면 참고자료 섹션을 필수로 작성해야 합니다. 가능한 경우 문서에 이름과 링크를 추가하여 출처를 표시하세요(디지털 문서가 아닌 경우 ISBN 또는 기타 참조 수단을 포함하세요).

스타일 가이드

• 작성 톤 - 튜토리얼은 커뮤니티 기여자가 동료를 위해 작성합니다.

  • 이러한 점을 고려하여 튜토리얼 전반에 걸쳐 포용과 상호 작용의 분위기를 조성하는 것이 좋습니다. "우리", "우리가", "우리의"와 같은 단어를 사용하세요.
    • 예시: "우리의 계약을 성공적으로 배포했습니다."
  • 직접적인 지시를 제공할 때는 "귀하", "귀하의" 등을 자유롭게 사용하세요.
    • 예시: "귀하의 파일은 다음과 같이 표시되어야 합니다:".

• 튜토리얼 전체에서 마크다운을 적절히 사용하세요. GitHub의 마크다운 가이드와 샘플 튜토리얼 구조를 참조하세요.

• 강조를 위해 미리 서식화된 텍스트를 사용하지 마세요, 예시:

  • ❌ "TON counter smart contract named counter.fc"는 잘못되었습니다.
  • ✅ "TON counter smart contract named counter.fc"는 올바릅니다.

• 섹션 제목에 markdown 서식을 사용하지 마세요, 예시:

  • ❌ #Introduction는 잘못되었습니다.
  • ✅ # Introduction는 올바릅니다.

• 코드를 설명하세요! 학습자에게 무작정 복사하여 붙여넣기만 하라고 하지 마세요.

  • 함수 이름, 변수, 상수는 문서 전체에 걸쳐 일관성을 유지해야 합니다.

  • 코드 블록의 시작 부분에 주석을 사용하여 코드가 있는 경로와 파일명을 표시합니다. 예시:

    // test-application/src/filename.jsx
    
    import { useEffect, useState } from 'react';
    
    ...

• 코드 블록 구문 강조 표시를 위해 적절한 언어를 선택하세요!

  • 모든 코드 블록에는 구문 강조 표시가 필수 있어야 합니다. 어떤 구문 강조 표시를 적용할지 잘 모르겠다면 ``\`텍스트를 사용하세요.

• 미리 형식이 지정된 텍스트에는 코드 블록 구문을 사용하지 마세요, 예시:

  • ❌ `filename.jsx` 는 잘못되었습니다.
  • ✅ `filename.jsx` 는 올바릅니다.

• 코드 블록은 주석이 잘 달려 있어야 합니다. 주석은 짧고(보통 한 번에 두세 줄) 효과적이어야 합니다. 코드를 설명하기 위해 더 많은 공간이 필요한 경우 코드 블록 외부에서 설명하세요.

• 모든 코드 블록 앞뒤에 빈 줄을 남겨두는 것을 잊지 마세요.
  예시:

  
// test-application/src/filename.jsx  
  
import { useEffect, useState } from 'react';
  

• 코드를 코드 블록에 붙여넣기 전에 linter 및 prettifier를 사용하세요. JavaScript/React에는 eslint를 권장합니다. 코드 서식 지정에는 prettier를 사용하세요.
• 글머리 기호, 번호 목록 또는 복잡한 텍스트 서식을 남용하지 마세요. 굵게 또는 이탤릭체 강조는 허용되지만 최소한으로 사용해야 합니다.

앱 설정

• Web3 프로젝트에는 일반적으로 여러 개의 기존 코드 라이브러리가 포함됩니다. 튜토리얼을 작성할 때 이를 고려해야 합니다. 가능하면 학습자가 쉽게 시작할 수 있도록 GitHub 리포지토리를 시작점으로 제공하세요.
• 튜토리얼에 사용하는 코드를 포함하기 위해 GitHub 리포지토리를 사용하지 않는 경우에는 독자들에게 코드를 정리할 폴더를 만드는 방법을 설명해 주세요. 예시: mkdir example && cd example
• npm init을 사용하여 프로젝트 디렉터리를 초기화하는 경우, 프롬프트를 설명하거나 -y 플래그를 사용합니다.
• npm install을 사용하는 경우 -save 플래그를 사용합니다.