Pengantar
Codelab adalah tutorial interaktif yang ditulis dalam sintaksis markdown. Kami memublikasikan codelab kami di blocklycodelabs.dev. Codelab menggunakan campuran natural language, 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 bagi komunitas. Ini adalah cara untuk berbagi pengetahuan dan mempermudah developer berikutnya yang mengalami masalah yang sama.
Apa yang membuat codelab yang hebat?
Codelab yang baik berfokus dan dapat dibaca. Hal ini memberi tahu pengguna apa yang akan mereka buat dan apa yang akan mereka pelajari dengan jelas, serta memandu pengguna untuk 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 contoh blockly. Sertakan deskripsi tentang apa yang ingin Anda ajarkan dan apa yang akan Anda bangun dalam codelab. Kami akan mendiskusikan dan menyempurnakan ide tersebut. Kemudian, Anda dapat menulisnya dan mengirimkan permintaan pull untuk hal tersebut. Setelah melalui peninjauan, anggota tim Blockly akan memublikasikannya.
Tips menulis
Bagian selanjutnya dari halaman ini adalah kumpulan tips dan pertanyaan untuk memandu Anda dalam menulis codelab.
Lihat Technical Writing One untuk pengantar singkat tentang penulisan teknis.
Audiens
- Siapa target pembacanya?
- Apa saja yang telah mereka ketahui tentang penggunaan Blockly?
- Apa yang ingin mereka pelajari?
Penyiapan
- Apa penyiapan minimum yang diperlukan agar pengguna dapat menjalankan kode Anda?
Jika membantu, Anda dapat memublikasikan kode awal
dan kode lengkap
di direktori examples.
Struktur
Seperti halnya tulisan lainnya, mulailah dengan membuat garis besar. Ini adalah struktur yang baik untuk sebagian besar codelab:
- Pengantar
- Yang akan Anda pelajari
- Yang akan Anda bangun
- 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 di sini]
- Ringkasan
- Yang telah Anda pelajari
- Yang Anda build
- Referensi lainnya
- Link ke kode yang sudah selesai (jika tersedia)
Meskipun Anda dapat memiliki lebih dari sepuluh langkah, jika mencapai dua puluh langkah, sebaiknya pertimbangkan untuk memecahnya menjadi dua codelab.
Gaya penulisan
- Gunakan gaya penulisan percakapan.
- Gunakan {i>heading<i} untuk membuat organisasi yang jelas.
- Gunakan daftar berbutir untuk memisahkan dinding teks.
- Gunakan gambar dan gif!
Gaya kode
- Anda dapat menulis dalam ES5, ES6, atau TypeScript, tetapi memberi tahu pembaca mana yang ada di awal.
- Ikuti panduan gaya Google