소개
Codelab은 마크다운 문법으로 작성된 대화형 튜토리얼입니다. Codelab은 blocklycodelabs.dev에서 게시됩니다. Codelab은 자연어, 코드 샘플, 스크린샷을 적절히 조합하여 더 흥미로운 튜토리얼 환경을 제공합니다. Codelab의 대상 사용자는 읽으면서 코드를 따라 실행합니다.
Codelab을 작성하면 커뮤니티에 기여할 수 있습니다. 지식을 공유하고 동일한 문제에 직면한 다음 개발자의 작업을 더 쉽게 만들어 주는 방법입니다.
우수한 Codelab의 조건
좋은 Codelab은 집중적이고 읽기 쉽습니다. 사용자에게 빌드할 항목과 학습할 내용을 명확하게 알려주고, 특정 작업을 완료하기 위해 코드를 작성하고 이해하는 방법을 안내합니다.
절차
Codelab에 대한 아이디어가 있으면 blockly-samples 저장소에서 기능 요청을 제출하여 알려주세요. 가르치려는 내용과 Codelab에서 빌드할 내용을 설명합니다. 아이디어를 논의하고 다듬습니다. 그런 다음 이를 작성하고 pull 요청을 제출할 수 있습니다. 검토가 완료되면 Blockly팀에서 게시합니다.
작성 시 도움말
이 페이지의 나머지 부분은 Codelab 작성을 안내하는 도움말과 질문으로 구성되어 있습니다.
기술 문서 작성에 관한 빠른 소개는 기술 문서 작성 1을 참고하세요.
잠재고객
- 타겟 독자는 누구인가요?
- Blockly 사용에 관해 이미 알고 있는 것은 무엇인가요?
- 무엇을 배우려고 하나요?
설정
- 사용자가 코드를 실행하는 데 필요한 최소 설정은 무엇인가요?
도움이 된다면 examples 디렉터리에 시작 코드 및 완료된 코드를 게시할 수 있습니다.
구조
다른 글쓰기와 마찬가지로 개요로 시작합니다. 다음은 대부분의 Codelab에 적합한 구조입니다.
- 소개
- 학습할 내용
- 빌드할 항목
- 알아야 할 사항
- 설정 안내
- 1단계: [여기에 제목 입력]
- 설명/동기
- 코드 샘플
- 예상 결과
- (선택사항) 추가 설명
- ...
- 10단계: [여기에 제목 입력]
- 요약
- 학습한 내용
- 빌드한 항목
- 추가 리소스
- 완성된 코드 링크 (있는 경우)
10단계를 초과할 수 있지만 20단계가 되면 두 개의 Codelab으로 나누는 것이 좋습니다.
작성 스타일
- 대화체 문체를 사용하세요.
- 제목을 사용하여 조직을 명확하게 표시합니다.
- 글머리기호 목록을 사용하여 긴 텍스트를 나누세요.
- 이미지와 GIF를 사용하세요.
코드 스타일
- ES5, ES6 또는 TypeScript로 작성할 수 있지만 시작 부분에서 어떤 언어를 사용하는지 독자에게 알려야 합니다.
- Google 스타일 가이드를 따릅니다.