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

그래서 TON 문서에 대한 튜토리얼을 작성하기로 결정하셨나요?

여러분과 함께하게 되어 기쁩니다! 아래 가이드라인을 검토하여 여러분의 튜토리얼이 톤 문서에 있는 기존 콘텐츠의 스타일과 품질을 따르고 있는지 확인하세요.

튜토리얼의 구조와 제목을 어떻게 사용해야 하는지 익숙해지는 데 시간을 할애하는 것이 중요합니다. 기존 튜토리얼을 읽어보시고 이전 풀 리퀘스트도 살펴본 후 직접 제출하시기 바랍니다.

프로세스

중요

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

또한 저희가 제공한 샘플 튜토리얼 구조를 참고하시기 바랍니다.

1. 시작하려면 GitHub에서 ton-docs 리포지토리를 포크한 다음 복제하고 로컬 리포지토리에 새 브랜치를 만드세요.
2. 품질과 가독성을 염두에 두고 튜토리얼을 작성하세요! 기존 튜토리얼을 살펴보고 무엇을 목표로 해야 하는지 알아보세요.
3. 검토를 위해 제출할 준비가 되면 지점에서 풀 리퀘스트를 열어서(https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) 제출하세요. 알림이 전송되고 검토 절차가 시작됩니다:
   1. 튜토리얼의 최종 초안만 제출하도록 최선을 다해 주세요. 일부 오타 및 문법 수정은 허용되지만 튜토리얼을 게시하기 전에 중대한 변경 사항이 있는 경우 검토하고 필요한 사항을 수정하는 데 시간이 오래 걸릴 수 있습니다.
4. 제출하신 내용을 검토하고 필요한 모든 변경을 완료하면 풀 리퀘스트를 병합하고 TON 문서에 튜토리얼을 게시합니다. 그 후 곧 연락을 드리고 결제를 준비하겠습니다!
5. 튜토리얼이 게시되면 소셜 미디어에 홍보하는 것을 잊지 마세요! 문서 유지 관리자](/contribute/maintainers)가 협조해 주시면 이 홍보를 확대하는 데 도움이 될 수 있습니다.

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

1. 포크 및 복제 **톤 문서** 리포지토리
2. 튜토리얼 작성 및 수정하기
3. 검토를 위해 풀 리퀘스트 제출하기
4. 필요한 변경 사항 적용
5. 튜토리얼이 병합되어 게시되었습니다.
6. 소셜 미디어에 튜토리얼을 홍보하세요!

컨텍스트

'TON' 앞에 'THE'를 추가하는 것에 대한 주요 이슈는 TON 문서 및 편집 정책을 개발하는 과정에서 마케팅, 벤더, 개발자 등 다양한 부서에서 하나의 시스템, 네트워크, 브랜드라는 강한 이미지를 만들기 위해 '블록체인', '에코시스템' 등과 같은 단어를 'TON'과 함께 대문자로 표기하자는 논의에 참여했다는 점입니다. 오랜 논의 끝에 강력한 브랜드 이미지를 위해 'THE'를 빼고 대문자로 표기할 수 있는 단어와 문구를 모아 용어집을 만들어야 한다는 결론을 내렸습니다. 대문자로 표기할 수 있는 경우 해당 용어집은 불필요합니다. 현재 이러한 단어 조합은 두 가지가 있습니다: TON 블록체인과 TON 생태계.

TON Connect, TON SDK, TON Grants 등과 같은 다른 TON 모듈 이름의 경우 상황에 따라 다릅니다. 대문자 규칙을 적용하지만 관사 규칙은 유연하게 적용할 수 있습니다. 컴포넌트 이름이 단독인 경우 관사가 없는 것이 좋습니다. 그러나 TON Connect 프로토콜과 같이 일반 명사와 결합된 경우에는 엔티티 프로토콜을 지칭하므로 관사가 필요합니다.

'TON + 명사'와 같은 다른 단어 조합(예: 'TON 세계', 'TON 커뮤니티' 등)의 경우, 해당 관사가 명사와 결합하여 사용되는 것을 자연스럽게 예상하기 때문에 관사의 사용을 제한하지 않습니다.

일반 팁

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

튜토리얼을 구성하는 방법

튜토리얼 구조 샘플

샘플 튜토리얼 구조](/contribute/tutorials/sample-tutorial)를 확인하여 직접 눈으로 확인해 보세요.

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

스타일 가이드

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

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

• 튜토리얼 내내 마크다운을 올바르게 사용하세요. GitHub의 마크다운 가이드](https://guides.github.com/features/mastering-markdown/)와 샘플 튜토리얼 구조를 참조하세요.

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

  • "TON 카운터 '스마트 컨트랙트'의 이름은 '카운터.fc'입니다."가 올바르지 않습니다.
  • ✅ "TON 카운터 스마트 컨트랙트 이름은 counter.fc"가 맞습니다.

• 섹션 제목에 마크다운 서식을 사용하지 마세요(예: 예시):

  • ❌ # 소개가 올바르지 않습니다.
  • ✅ # 소개가 맞습니다.

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

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

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

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

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

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

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

  • ❌ `파일 이름`이 올바르지 않습니다.
  • ✅ `파일명`이 맞습니다.

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

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

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

• 코드를 코드 블록에 붙여넣기 전에 린터 및 프리티파이어를 사용하세요. 자바스크립트/리액트에는 eslint를 권장합니다. 코드 서식 지정에는 prettier를 사용하세요.
• 글머리 기호, 번호가 매겨진 목록 또는 복잡한 텍스트 서식을 남용하지 마세요. 굵게** 또는 이탤릭체 강조는 허용되지만 최소한으로 사용해야 합니다.

앱 설정

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