Pengantar
Codelab adalah tutorial interaktif yang ditulis dalam sintaks Markdown. Kami memublikasikan codelab di blocklycodelabs.dev. Codelab menggunakan campuran bahasa alami, contoh kode, dan screenshot untuk menciptakan pengalaman tutorial yang lebih menarik. Pengguna target codelab mengikuti dan menjalankan kode saat mereka membaca.
Menulis codelab adalah cara yang bagus untuk berkontribusi pada komunitas. Cara ini dapat membagikan pengetahuan Anda dan mempermudah developer berikutnya yang mengalami masalah yang sama.
Apa yang membuat codelab menjadi luar biasa?
Codelab yang bagus berfokus dan mudah dibaca. Jelas memberi tahu pengguna apa yang akan mereka bangun dan pelajari, serta memandu pengguna menulis dan memahami kode untuk menyelesaikan tugas tertentu.
Proses
Jika memiliki ide untuk codelab, Anda dapat memberi tahu kami dengan membuat permintaan fitur di repositori blockly-samples. Sertakan deskripsi tentang apa yang ingin Anda ajarkan dan apa yang akan Anda bangun di codelab. Kita akan mendiskusikan dan menyempurnakan ide tersebut. Kemudian, Anda dapat menuliskannya dan mengirimkan permintaan pull untuk itu. Setelah melalui peninjauan, anggota tim Blockly akan memublikasikannya.
Tips menulis
Bagian selanjutnya dari halaman ini berisi serangkaian tips dan pertanyaan untuk memandu Anda menulis codelab.
Lihat Technical Writing One untuk pengantar singkat tentang penulisan teknis.
Audiens
- Siapa target pembacanya?
- Apa yang sudah mereka ketahui tentang penggunaan Blockly?
- Apa yang ingin mereka pelajari?
Penyiapan
- Apa penyiapan minimum yang diperlukan agar pengguna dapat menjalankan kode Anda?
Jika perlu, Anda dapat memublikasikan kode awal
dan kode lengkap
di direktori examples.
Struktur
Seperti halnya tulisan apa pun, mulailah dengan kerangka. Ini adalah struktur yang baik untuk sebagian besar codelab:
- Pengantar
- Yang akan Anda pelajari
- Yang akan Anda build
- Yang perlu Anda ketahui
- Petunjuk penyiapan
- Langkah pertama: [Judul di sini]
- Penjelasan/motivasi
- Contoh kode
- Hasil yang diharapkan
- (Opsional) Penjelasan lebih lanjut
- ...
- Langkah sepuluh: [Judul ada di sini]
- Ringkasan
- Yang telah Anda pelajari
- Yang Anda bangun
- Referensi lainnya
- Link ke kode yang sudah selesai (jika tersedia)
Meskipun Anda dapat memiliki lebih dari sepuluh langkah, jika Anda mencapai dua puluh langkah, Anda harus mempertimbangkan untuk membaginya menjadi dua codelab.
Gaya penulisan
- Gunakan gaya penulisan percakapan.
- Gunakan judul untuk memperjelas organisasi.
- Gunakan daftar berbutir untuk memecah teks yang panjang.
- Gunakan gambar dan GIF.
Gaya kode
- Anda dapat menulis dalam ES5, ES6, atau TypeScript, tetapi beri tahu pembaca di awal.
- Ikuti panduan gaya Google