좋은 Codelab 작성

소개

Codelab은 마크다운 문법으로 작성된 대화형 튜토리얼입니다. Codelab은 blocklycodelabs.dev에 게시됩니다. Codelab은 자연어, 코드 샘플, 스크린샷을 조합하여 더욱 재미있는 튜토리얼 환경을 만듭니다. Codelab의 타겟 사용자는 코드를 읽고 따라가며 실행합니다.

Codelab을 작성하는 것은 커뮤니티에 기여하는 좋은 방법입니다. 지식 공유를 통해 지식을 공유하고 같은 문제에 직면한 다음 개발자가 편하게 일하도록 할 수 있습니다.

훌륭한 Codelab의 조건

우수한 Codelab은 집중력이 높고 읽기 쉽습니다. 사용자에게 빌드할 내용과 학습할 내용을 명확하게 알리고, 사용자가 특정 작업을 완료하기 위해 코드를 작성하고 이해하는 방법을 안내합니다.

프로세스

Codelab에 관한 아이디어가 있다면 블록리 샘플 저장소에서 기능 요청을 통해 알려 줄 수 있습니다. 교육할 내용과 Codelab에서 빌드할 내용에 관한 설명을 포함하세요. 아이디어에 대해 논의하고 수정하겠습니다. 그런 다음 이를 작성하여 pull 요청을 제출할 수 있습니다. 검토가 완료되면 Blockly팀원이 게시합니다.

작성 시 도움말

이 페이지의 나머지 부분에서는 Codelab 작성을 안내하는 도움말과 질문 세트를 제공합니다.

기술 글쓰기에 관한 간단한 소개는 테크니컬 라이팅 1을 참고하세요.

대상

  • 타겟 독자는 누구인가요?
  • 기업에서 Blockly를 사용하는 것에 대해 이미 알고 있는 것은 무엇인가요?
  • 고객이 배우고자 하는 것이 무엇인가?

설정

  • 사용자가 코드를 실행하는 데 필요한 최소 설정은 무엇인가요?

도움이 되는 경우 examples 디렉터리에 시작 코드와 완성된 코드를 게시할 수 있습니다.

구조

다른 글과 마찬가지로 개요로 시작하세요. 이는 대부분의 Codelab에 적합한 구조입니다.

  • 소개
    • 학습할 내용
    • 빌드할 항목
    • 알아 두어야 할 사항
    • 설정 안내
  • 1단계: [여기에 제목 삽입]
    • 설명/동기
    • 코드 샘플
    • 예상 결과
    • (선택사항) 추가 설명
  • ...
  • 10단계: [여기에 제목 삽입]
  • 요약
    • 학습 완료한 내용
    • 빌드한 항목
    • 추가 리소스
    • 완성된 코드에 대한 링크 (제공되는 경우)

10개 이상의 단계가 있을 수 있지만 20단계를 달성하면 두 개의 Codelab으로 나누는 것이 좋습니다.

작성 스타일

  • 대화식 글쓰기 스타일을 사용하세요.
  • 제목을 사용하여 내용을 명확하게 표시하세요.
  • 글머리기호 목록을 사용하여 텍스트 벽을 넓힙니다.
  • 이미지와 GIF를 사용하세요.

코드 스타일

  • ES5, ES6 또는 TypeScript로 작성할 수 있지만 어떤 내용이 시작 부분에 있는지 독자에게 알립니다.
  • Google 스타일 가이드 따르기