Giriş
Codelab, Markdown söz diziminde yazılmış etkileşimli bir eğitimdir. Codelab'lerimizi blocklycodelabs.dev adresinde yayınlıyoruz. Codelab'ler, daha ilgi çekici bir eğitim deneyimi oluşturmak için doğal dil, kod örnekleri ve ekran görüntülerinin bir karışımını kullanır. Bir kod laboratuvarının hedef kullanıcısı, kod laboratuvarını takip ediyor ve kodları okurken çalıştırıyor.
Codelab yazmak, topluluğa katkıda bulunmanın mükemmel bir yoludur. Bu sayede, bilgilerinizi paylaşabilir ve aynı sorunla karşılaşacak bir sonraki geliştiricinin hayatını kolaylaştırabilirsiniz.
Codelab'i başarılı kılan özellikler nelerdir?
İyi bir kod laboratuvarı odaklanmış ve okunaklı olmalıdır. Kullanıcıya ne oluşturacağını ve ne öğreneceğini açıkça belirtir ve belirli bir görevi tamamlamak için kod yazma ve anlama konusunda kullanıcıya yol gösterir.
İşleme
Codelab için fikriniz varsa blockly-samples deposunda özellik isteği göndererek bize bildirebilirsiniz. Codelab'de öğretmek istediğiniz konuyu ve oluşturacağınız içeriği açıklayın. Fikrinizi tartışıp daha da geliştireceğiz. Ardından, bu değişikliği yazıp bir çekme isteği gönderebilirsiniz. İnceleme yapıldıktan sonra Blockly ekibinin bir üyesi tarafından yayınlanır.
Yazmayla ilgili ipuçları
Bu sayfanın geri kalanında, kod laboratuvarı yazma konusunda size yol gösterecek ipuçları ve sorular verilmiştir.
Teknik yazıya hızlı bir giriş için Teknik Yazma Bir başlıklı makaleyi inceleyin.
Kitle
- Hedef okuyucu kim?
- Blockly'yi kullanma konusunda ne biliyorlar?
- Ne öğrenmeye çalışıyorlar?
Kurulum
- Kullanıcının kodunuzu çalıştırması için gereken minimum kurulum nedir?
Faydalı olacağını düşünüyorsanız examples dizininde başlangıç kodunu ve tamamlanmış kodu yayınlayabilirsiniz.
Yapı
Her yazıda olduğu gibi, bir ana hatla başlayın. Bu, çoğu kod laboratuvarı için iyi bir yapıdır:
- Giriş
- Neler öğreneceksiniz?
- Ne oluşturacaksınız?
- Bilmeniz gerekenler
- Kurulum talimatları
- Birinci adım: [Başlık buraya yazılır]
- Açıklama/motivasyon
- Kod örneği
- Beklenen sonuçlar
- (İsteğe bağlı) Daha fazla açıklama
- ...
- Onuncu adım: [Başlık buraya yazılır]
- Özet
- Öğrendikleriniz
- Oluşturduğunuz içerikler
- Ek kaynaklar
- Tamamlanmış kodun bağlantısı (varsa)
Ondan fazla adımınız olabilir ancak yirmiye yaklaşıyorsanız kodu iki Codelab'e ayırabilirsiniz.
Yazma stili
- Sohbet tarzında bir yazım stili kullanın.
- Düzenlemeyi netleştirmek için başlıkları kullanın.
- Metin bloklarını bölmek için madde işaretli listeleri kullanın.
- Resim ve GIF kullanın.
Kod stili
- ES5, ES6 veya TypeScript'te yazabilirsiniz ancak hangisini kullandığınızı baştan belirtin.
- Google stil kılavuzuna uyun