Giriş
Codelab, Markdown söz dizimiyle yazılan etkileşimli bir eğitimdir. Codelab'lerimizi blocklycodelabs.dev adresinde yayınlıyoruz. Codelab'ler daha ilgi çekici bir eğitim deneyimi sunmak için doğal dil, kod örnekleri ve ekran görüntülerini bir arada kullanır. Bir codelab'in hedef kullanıcısı, kodu okurken izlemektedir.
Codelab yazmak, topluluğa katkıda bulunmanın mükemmel bir yoludur. Böylece hem bildiklerinizi paylaşabilir hem de aynı sorunla karşılaşacak bir sonraki geliştiricinin hayatını kolaylaştırabilirsiniz.
Mükemmel bir codelab'in özellikleri nelerdir?
Başarılı bir codelab'in amacı iyi odaklanmış ve okunabilir durumdadır. Kullanıcıya ne geliştireceğini ve ne öğreneceğini açıkça söyler ve belirli bir görevi tamamlamak için kodu yazıp anlaması konusunda kullanıcıya yol gösterir.
İşleme
Bir codelab fikriniz varsa blok halindeki örnekler deposunda özellik isteğinde bulunarak bu fikri bize bildirebilirsiniz. Codelab'de öğretmek istediğiniz ve geliştireceğiniz şeyin bir açıklamasını ekleyin. Bu fikri tartışıp netleştireceğiz. Daha sonra bunu yazabilir ve bunun için bir pull isteği gönderebilirsiniz. İnceleme tamamlandıktan sonra Blockly ekibinin bir üyesi yayını yayınlar.
Yazmayla ilgili ipuçları
Bu sayfanın geri kalanında, kod laboratuvarı yazarken size rehberlik edecek ipuçları ve sorular yer almaktadır.
Teknik yazmaya hızlı giriş için Technical Write 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ırabilmesi için gereken minimum kurulum nedir?
Yardımcı olacaksa başlangıç kodunu ve tamamlanan kodu examples dizininde yayınlayabilirsiniz.
Yapı
Her yazıda olduğu gibi, bir ana hatla 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
- Yapınız
- Ek kaynaklar
- Tamamlanan kodun bağlantısı (varsa)
10'dan fazla adımınız olabilir, ancak yirmiye ulaşıyorsanız bunu iki codelab'e bölebilirsiniz.
Yazma stili
- Konuşmaya dayalı bir yazı stili kullanın.
- Kuruluşu 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 dilinde yazabilirsiniz, ancak okuyucuya bunun en başta hangisi olduğunu söyleyin.
- Google stil kılavuzundaki talimatları uygulayın