Pengantar
Codelab adalah tutorial interaktif yang ditulis dalam sintaksis Markdown. Kami memublikasikan codelab di blocklycodelabs.dev. Codelab menggunakan gabungan 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. Ini adalah cara untuk berbagi pengetahuan dan memudahkan developer berikutnya yang mengalami masalah yang sama.
Apa yang membuat codelab menjadi luar biasa?
Codelab yang bagus bersifat terfokus dan mudah dibaca. Panduan ini memberi tahu pengguna dengan jelas apa yang akan mereka bangun dan apa yang akan mereka 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 contoh blockly. Sertakan deskripsi tentang hal yang ingin Anda ajarkan dan hal yang akan Anda buat di codelab. Kita akan membahas dan meningkatkan kualitas ide tersebut. Kemudian, Anda dapat menulisnya dan mengirimkan permintaan pull untuk fitur tersebut. Setelah melalui peninjauan, anggota tim Blockly akan memublikasikannya.
Tips menulis
Bagian halaman ini adalah serangkaian tips dan pertanyaan untuk memandu Anda dalam 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 mereka coba pelajari?
Penyiapan
- Apa penyiapan minimum yang diperlukan pengguna untuk menjalankan kode Anda?
Jika membantu, Anda dapat memublikasikan kode awal
dan kode yang sudah selesai
di direktori examples.
Struktur
Seperti halnya tulisan apa pun, mulailah dengan membuat garis besar. 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 selengkapnya
- ...
- Langkah sepuluh: [Title goes here]
- 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 bagi menjadi dua codelab.
Gaya penulisan
- Gunakan gaya penulisan percakapan.
- Gunakan judul untuk memperjelas organisasi.
- Gunakan daftar berbutir untuk memecah dinding teks.
- Gunakan gambar dan gif.
Gaya kode
- Anda dapat menulis dalam ES5, ES6, atau TypeScript, tetapi beri tahu pembaca mana yang digunakan di awal.
- Ikuti panduan gaya Google