Yazılım Eğitimleri Yazma Kuralları

• Çoğu yazılım eğitimi, önemli ayrıntıları atladığı veya okuyucunun beklentileriyle uyuşmayan gizli varsayımlar içerdiği için okuyucunun süreci yeniden üretmesini imkansız hale getirir
• Birkaç basit kurala uyarsanız, düşündüğünüzden daha kolay şekilde mükemmel eğitimler yazabilirsiniz

Kurallar

1. Yeni başlayanlar için yazın
2. Net bir sonuç vaat eden bir başlık yazın
3. Girişte hedefi açıklayın
4. Nihai sonucu önceden gösterin
5. Kopyala/yapıştır yapılabilir kod parçaları yazın
6. Komutlarda uzun bayraklar kullanın
7. Kullanıcıya özel değerlerle yeniden kullanılabilir mantığı ayırın
8. Okuyucunun uğraşını azaltın
9. Kodu her zaman çalışır durumda tutacak şekilde yazın
10. Yalnızca tek bir konu öğretin
11. Süslemeden önce açıklığı tercih edin
12. Bağımlılıkları en aza indirin
13. Dosya adlarını açıkça belirtin
14. Tutarlı ve açıklayıcı başlıklar kullanın
15. Çözümün çalıştığını kanıtlayın
16. Tam örneğe bağlantı verin

Yeni başlayanlar için yazın

• Eğitimlerde en yaygın hata, başlangıç seviyesindeki kavramları uzman düzeyindeki terimlerle açıklamaktır. Eğitim arayan insanların çoğu yeni başlayandır.
  • Programlamaya yeni başlamamış olabilirler, ancak öğrenmek istedikleri alanda yenidirler
• Yeni başlayanları hedefleyin ve uzman düzeyindeki terminolojiden kaçının
• Zor terimlerden uzak durun ve okuyucunun anlayabileceği sade bir dille yazın
• Örneğin bir React eğitiminde, "JSX transpilation" yerine "React ile basit bir web sayfası oluşturma" gibi bir açıklama verin

Net bir sonuç vaat eden bir başlık yazın

• Başlık, okuyucunun eğitimden tam olarak ne öğreneceğini somut biçimde aktarmalıdır
• Belirsiz veya muğlak başlıklardan kaçının; beklenen sonucu açıkça anlatın
  • Örnek: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"

Girişte hedefi açıklayın

• Okuyucu eğitime tıkladığında, zaten söylediklerinizle ilgileniyor demektir. Ama onu okumaya devam etmeye ikna etmeniz gerekir
• Okuyucunun merak ettiği iki şey vardır
  • Bu teknolojiyle neden ilgilenmeliyim?
  • İlgileniyorsam, bu eğitim benim için uygun mu?
• Girişte teknolojinin önemini ve eğitimin faydasını kısa ve net biçimde açıklayın
• Okuyucunun ilgisini çekecek yararlı bilgiler verin ve muğlak anlatımdan kaçının
  • Örnek: Bir Docker eğitimi, Docker'ın çözdüğü problemi ve beklenen sonucu açıkça açıklamalıdır

Nihai sonucu önceden gösterin

• Mümkün olduğunca erken, okuyucunun eğitim sonunda yapacağı şeyin demosunu veya ekran görüntüsünü gösterin
  • Nihai sonucu eğitimin başlarında göstererek hedefi netleştirin
• Örneğin nihai ürünün ekran görüntüsü, arayüzü veya çalışma örneğini verin

Kopyala/yapıştır yapılabilir kod parçaları yazın

• Kodları, okuyucunun kolayca kopyalayıp düzenleyicisine veya terminaline yapıştırarak çalıştırabileceği şekilde yazın
• Terminal istemi karakteri $ gibi gereksiz unsurları kaldırın
• Komutları sadeleştirmek için etkileşimsiz bayraklar kullanın ve başarısızlık durumunda durması için && kullanın

Komutlarda uzun bayraklar kullanın

• Kısa bayraklar yerine açıklaması daha net olan uzun bayrakları kullanın ki yeni başlayanlar da kolayca anlayabilsin
  • -r yerine --recursive

Kullanıcıya özel değerlerle yeniden kullanılabilir mantığı ayırın

• Kod içinde kullanıcının değiştirmesi gereken değerlerle değiştirmemesi gereken kodu açıkça ayırın
• Kullanıcıya özel değerleri ortam değişkenleriyle tanımlayarak kodun okunabilirliğini artırın

Okuyucunun uğraşını azaltın

• Okuyucunun eğitimi sevmesini istiyorsanız, zamanına saygı gösterin
• Sıkıcı işleri yaptırmak yerine bunları komut parçalarıyla değiştirin
  • Örnek: Dosyayı elle düzenletmek yerine bunu bir komutla çözün

Kodu her zaman çalışır durumda tutacak şekilde yazın

• Örnek kod her zaman çalıştırılabilir olmalı ve ara adımlarda da çalışır durumda kalmalıdır
• Hatalı kod veya çalışmayan örnekler okuyucuda kafa karışıklığı yaratır

Yalnızca tek bir konu öğretin

• Eğitimi tek bir konu etrafında kurun ve ilgisiz teknolojileri karıştırmayın
• Örneğin arama işlevini anlatan bir eğitime gereksiz yapay zeka teknolojileri eklemeyin

Süslemeden önce açıklığı tercih edin

• Okuyucu, oyuncak bir uygulamanın güzel görünüp görünmediğini umursamaz
• Gereksiz CSS veya tasarım öğelerini en aza indirin ve temel kavramlara odaklanın
• Karmaşık örnekler yerine basit kodla kavramı net biçimde aktarın

Bağımlılıkları en aza indirin

• Okuyucunun kurması gereken bağımlılıkları en aza indirerek eğitimin erişilebilirliğini artırın
• Gerekli bağımlılıkları açıkça belirtin ve belirli sürümleri yazın

Dosya adlarını açıkça belirtin

• Okuyucuya düzenlemesi gereken dosya yolunu ve içeriği tam olarak söyleyin
• Örneğin "config dosyasına ayar ekleyin" demek yerine, tam dosya yolunu ve tam olarak hangi satırın düzenleneceğini gösteren somut kod verin

Tutarlı ve açıklayıcı başlıklar kullanın

• Okuyucunun eğitimi hızlıca tarayabilmesi için yapılandırılmış başlıklar kullanın
• Eğitimi başlıklarla yapılandırın ve başlıkların mantıksal yapıyı yansıtmasını sağlayın
• Başlıkların biçimini, bakış açısını ve zaman kipini tutarlı tutun

Çözümün çalıştığını kanıtlayın

• Eğitim araç kurulumu veya birden fazla bileşenin entegrasyonunu öğretiyorsa, ortaya çıkan sonucu nasıl kullanacağını gösterin
  • Kurulan ve entegre edilen araçların çalışma sonucunu okuyucuya görsel olarak gösterin
• Örneğin nginx başarı sayfasını gösterin ve URL üzerinden nasıl doğrulanacağını anlatın

Tam örneğe bağlantı verin

• Eğitimin tüm kodlarını içeren bir depoya bağlantı vererek tüm akışın görülebilmesini sağlayın
• Her adımın kodunu ayrı bir git branch'ine bölerek okuyucunun adım adım takip edebilmesini sağlayın

[godogi7]

Referans için

[wedding]

Böyle şeyler için yer imi!

[ilikeall]

Güzel bir yazı.

[halfenif]

Geçenlerde dagster’ın tutorial’ını takip ettim. İyi hazırlanmış diye düşündüm.

https://courses.dagster.io/

[aer0700]

Dagster eğitimlerine şöyle bir göz attım, gerçekten çok iyiler.
Django eğitimleri içerik olarak dolu ama fazla uzun olduğu için ben pek sevmiyorum. Keşke biraz bölünse.

[savvykang]

İyi hazırlanmış bir tutorial örneği olarak Django da var: https://docs.djangoproject.com/en/5.1/intro/tutorial01/

[jhj0517]

Basit bir dil kullanın ve nihai sonucu en başta gösterin.

[aer0700]

Framework'ün sıkıcı temel kullanımını göstermek yerine,
bu framework'ün ne kadar havalı olduğunu göstermeye çalışan tutorial belgeleri bazen oluyor.
Get started bölümüne giriyorum ama temel kullanım tutorial'ı diye işaretlenen şey 10 sayfalık bir belgeyse bundan hiç hoşlanmıyorum.

[beenzinozino]

Herkes inanılmaz derecede etkileyici...

[savvykang]

https://tanstack.com/table/latest/docs/introduction

[nono9633]

https://github.com/tmux/tmux/wiki/Getting-Started