Giriş
Codelab, Markdown söz diziminde yazılmış etkileşimli bir eğitimdir. Codelab'lerimizi blocklycodelabs.dev adresinde yayınlıyoruz. Codelab'lerde daha ilgi çekici bir eğitici deneyimi oluşturmak için doğal dil, kod örnekleri ve ekran görüntüleri bir arada kullanılır. Bir codelab'in hedef kullanıcısı, okurken kodu çalıştırır.
Bir codelab yazmak, topluluğa katkıda bulunmanın harika bir yoludur. Bu sayede, bilginizi paylaşabilir ve aynı sorunla karşılaşan diğer geliştiricilerin hayatını kolaylaştırabilirsiniz.
İyi bir codelab'in özellikleri nelerdir?
İyi bir codelab odaklanmış ve okunabilir olmalıdır. Kullanıcıya ne inşa edeceğini ve ne öğreneceğini net bir şekilde anlatır. Ayrıca, belirli bir görevi tamamlamak için kod yazma ve kodu anlama konusunda kullanıcıya yol gösterir.
İşleme
Bir codelab fikriniz varsa blockly-samples deposunda özellik isteğinde bulunarak bize bildirebilirsiniz. Eğitmek istediğiniz ve kod laboratuvarında oluşturacağınız şeylerin açıklamasını ekleyin. Fikri tartışıp iyileştireceğiz. Ardından bunu yazabilir ve çekme isteği gönderebilirsiniz. İnceleme sürecinden geçen bloklar, Blockly ekibinin bir üyesi tarafından yayınlanır.
Yazmayla ilgili ipuçları
Bu sayfanın geri kalanında, bir codelab yazma sürecinde size yol gösterecek ipuçları ve sorular yer almaktadır.
Teknik yazıma hızlı bir giriş için Technical Writing One'a göz atın.
Kitle
- Hedef okuyucu kim?
- Blockly'yi kullanma konusunda neler biliyorlar?
- Ne öğrenmeye çalışıyorlar?
Kurulum
- Kullanıcının kodunuzu çalıştırması için gereken minimum kurulum nedir?
Gerekirse examples dizininde başlangıç kodu ve tamamlanmış kodu yayınlayabilirsiniz.
Yapı
Her türlü yazıda olduğu gibi, ana hatlarla başlayın. Bu, çoğu codelab 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 gelecek]
- Açıklama/motivasyon
- Kod örneği
- Beklenen sonuçlar
- (İsteğe bağlı) Daha fazla açıklama
- ...
- Onuncu adım: [Başlık buraya gelecek]
- Özet
- Öğrendikleriniz
- Oluşturduğunuz öğeler
- Ek kaynaklar
- Tamamlanmış kodun bağlantısı (varsa)
On adımlı bir codelab oluşturabilirsiniz ancak yirmi adımı geçerseniz codelab'i ikiye bölmeyi düşünebilirsiniz.
Yazma stili
- Sohbet tarzında yazın.
- Düzeni netleştirmek için başlıkları kullanın.
- Metin duvarlarını bölmek için madde işaretli listeler kullanın.
- Resim ve GIF kullanın.
Kod stili
- ES5, ES6 veya TypeScript ile yazabilirsiniz ancak okuyucuya hangi dilde yazdığınızı en başta belirtmeniz gerekir.
- Google Stil Kılavuzu'na uyun.