Ben acemi bir geliştirici değilken, sizin (geliştirici olarak) benim için yazdığınız eğitimi nasıl okuyorum
(anniemueller.com)- Acemi birinin geliştiricilerin yazdığı teknik eğitimleri okurken yaşadığı kafa karışıklığını ve engelleri mizahi bir dille anlatan bir yazı
- Geliştiricilerin sık kullandığı uzmanlık terimleri ve kısaltmalar, acemilere bağlamı olmayan birer 'uzaylı dili' gibi geliyor
- Eğitimlerdeki kurulum adımları, dosya yolları ve terminal komutları çoğu zaman fazla karmaşık ya da eksik bırakıldığı için anlaşılması zor oluyor
- Yazar, geliştirici açısından çok doğal görünen açıklamaların acemiler için saatlerce arama ve deneme-yanılma gerektiren engellere dönüştüğünü söylüyor
- Bu yazı, eğitim yazan geliştiricilere başlangıç seviyesindeki birinin bakış açısından daha nazik ve daha açık anlatmaları gerektiğini hatırlatıyor
Yazının arka planı ve mesele
- Yazar, geliştirici olmayan bir acemi olarak geliştiricilerin yazdığı eğitimleri okurken yaşadıklarını anlatıyor
- Eğitimlerde geçen teknik terimlerin ve araç adlarının ne anlama geldiğine dair hiçbir fikrinin olmamasını hicivli bir şekilde aktarıyor
- Örneğin Hoobijag, Snarfus, Shamrock portal gibi uydurma teknik adlar kullanarak, bir aceminin gözünde her şeyin ne kadar karmaşık göründüğünü vurguluyor
Metnin çevirisi
“Merhaba! Ben bir geliştiriciyim. İlgili deneyimim şöyle: Hoobijag ile kod yazıyorum, bazen jabbernocks da kullanıyorum ve tabii ki ABCDE++++ de yapıyorum (ama asla ABCDE+/^+ değil, o tam bir saçmalık, değil mi? Hahaha!) Ayrıca Shoobababoo ile çalışmayı seviyorum, arada kleptomitrons da uğraşıyorum. Company[1]'de Shoobaboo ile ilgili bazı kodlar üzerinde çalıştım ve bu da beni Snarfus'a götürdü. Hadi başlayalım!
Bu eğitim hakkında
Snarfus ile ilk kez çok basit bir şey[2] yapmaya başladım ama kullandıkça ne kadar potansiyelli olduğunu gördüm! chromus biraz dağınık ama aslında inanılmaz derecede çok yönlü. Bu yüzden hoobastank yerine quagmire ile pintafore'u argyle etmeye başladım! Çılgınca, biliyorum. Ama bir bakıma çalıştı ve açıkçası oldukça eğlenceliydi… ta ki büyük bir engele çarpana kadar: fisterfunk, shamrock portal ile hiç konuşmuyor ve Snarfus'a beep-boops da göndermiyor! Tabii bunun ne anlama geldiğini biliyorsunuzdur[3]— artık tüm hoob-tüneli gramelions ile tıkanmış durumda. Kabul edilemez.
Neredeyse vazgeçiyordum ama sonra fark ettim ki backside Snarfus stagnator'u backside shamrock Klingon troglodyte emulater'a bağlayınca sorun çözülüyor! Her şey beep-boops ve ding-dongs yapmaya başladı ve sonunda eğitimin asıl konusuna gelebildim. Sonunda istediğiniz şekilde çok basit bir şey yapabiliyorsunuz! Oldukça havalı, değil mi[4].
Yani kurulum şöyle:
- Terminale
ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfasyazın - Şimdi
folder/hidden/deep/in/the/file/system/surprise!.filekonumuna gidin ve dosyanın içeriğini kopyalayın. Eğer orada yoksa,library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.fileiçinde olabilir - Tekrar terminale dönün, dosya içeriğini yapıştırın ve
64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][[]()()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!!yazın - Boop![5]
- Snarfus'u açın ve az önce oluşturduğunuz dosyayı yükleyin
- Sırf eğlencesine, chronostatiomatrix'in sham'ini kaldırmak isterseniz
—()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][]komutunu da çalıştırabilirsiniz. Bu isteğe bağlıdır - Tamamdır!
Nasıl gittiğini bana söyleyin. Bir de birilerinin bu yöntemi GewGawGamma ya da ometer2.7 ile kullanıp kullanmadığını merak ediyorum.”
Dipnot açıklamaları
- Muhtemelen ünlü bir şirket ama ben bilmiyorum
- Hiç de basit değil
- Ne anlama geldiğini bilmiyorum
- Havalı görünüyor ama ben yine de anlamadım. Yine de sizin yapabiliyor olmanıza sevindim
- İlk 3 adım muhtemelen yaklaşık 7 saat ve 193 arama gerektirecek. Ama Boop!'a ulaştığınızda gerçekten çok heyecan verici oluyor
Kapanış
- “Bu sadece eğlence için yazılmış bir yazı. Bilgilerini paylaşan ve eğitim yazan herkese içtenlikle teşekkür ederim.”
1 yorum
Hacker News yorumları
Birine yalnızca asgari düzeyde bilgi verip dokümantasyonu takip etmesini sağlama ve yanında sessizce izleme yaklaşımını şiddetle öneririm. Bu sırada hiç yardım etmeyip sadece gözlemlemek gerekir. Bu süreçte kullanıcının nerede takıldığını, yazarın fazla aşina olduğu için fark etmediği noktaları ya da eksik kalan ayarları ve benzeri birçok sorunu keşfedebilirsiniz. Kullanıcı fazla stres yaşamadan hedefine ulaşırsa dokümantasyon testi geçmiş demektir. Aksi halde başarısız olunan her noktayı eksiksiz kaydetmek, her birini iyileştirdikten sonra yeni biriyle tekrar test etmek gerekir. FAANG gibi büyük şirketlerin dokümantasyonunda bile bu standardı geçemeyen şeyler kullandım. Kuruluşumuzun yüksek standartlar koymuş olmasına gerçekten minnettarım. Bu şekilde dokümantasyon hazırlarsanız tekrarlayan toplantılar, destek talepleri ve görüntülü aramalar azalır; kullanıcılar da sorunlarını kendi başlarına çözebilir
Blog yazısının başlığı "Ben bir geliştirici değilim, senin yazdığın tutorial'ı okuyorum" idi, ama HN başlığı "Ben acemi bir geliştiriciyim..." olarak değiştirildi. Geliştirici olmayan biri ile acemi geliştirici tamamen farklı şeylerdir. Örneğin İK ekibi ya da tamamen alakasız bir alandan gelen biri için şirket içi terimler ve kavramlar baştan sona yabancı olabilir. Bu durumda geliştirici tamamen kopuk bir açıklama yazdıysa eleştirilmeyi hak eder. Buna karşılık acemi geliştirici zor da olsa yeni terimleri ve kavramları kendisi araştırabilir ve zamanla yeni gelen başka acemiler için dokümantasyonu güncelleyebilir
Çoğu tutorial geliştirici olmayanlar için değil, daha çok geliştiricilerin kendi aralarında bilgi paylaşması için yazılıyor; belirli bir bilgi topluluğuna yönelik akademik makalelere benzer bir konumda. Bunun kendisi de kötü değil. Hatta benim geçmişte bıraktığım notları yeniden bulmam açısından da işe yarıyor. Bu yüzden başlangıç seviyesine yönelik ayrı kurslar ve ders materyalleri var. Eğer tutorial'lar her seferinde 30 bin karakterlik tüm arka plan açıklamasıyla başlamak zorunda olsaydı, kimse sonuna kadar okumazdı. Tersine, ne kadar fazla arka plan eklerseniz ekleyin birileri için yine de yetersiz kalabilir
Pek çok teknik yazar "bilginin laneti"ni yeterince fark etmiyor. Eskiden bir WoW (World of Warcraft) guild'i yönetmiştim. 40 kişi aynı anda toplanıp bir dungeon'a giriyor, birlikte birçok boss ile savaşıyordu; küçücük bir hata bile tüm grubun ölmesine yol açabiliyordu. Bu yüzden herkes Teamspeak'te toplanır, stratejileri önceden uzun uzun anlatırdık. Buradaki en büyük dersler şunlardı: "Karşındakinin ne dediğini bilmediğini varsay" ve "Bir kez söylediklerini tekrar et". İnsanlar çoğu zaman bir şey bilmediklerinde araya girip sormuyor; bu yüzden sürekli "şu an hangi terimi kullanıyorum?", "bu kavramı bilmiyor olabilirler" diye kendime sorup ek açıklama yapma alışkanlığı olağanüstü etkili olmuştu. Bu tür iletişim deneyimleri teknik iletişime de birebir aktarılabiliyor; "bilginin laneti"ni aşma çabası refleks haline gelirse başkalarının anlama düzeyi ciddi biçimde artıyor
Birçok proje ana sayfası ya da GitHub README'si sanki "bunu okuyan zaten her şeyi biliyor" tavrıyla yazılıyor. Ben dokümanlara bakarken "bu araç neden gerekli", "hangi sorunu çözüyor", "benzer başka araçlardan farkı ne", "hâlâ aktif kullanılıyor mu", "artı ve eksileri karşılaştırabilmem için bana yeterince malzeme veriyor mu" gibi bir özen görmeyi isterdim. Sadece 5 dakikanızı ayırıp "tam bir acemi olsaydı neyi merak ederdi?" diye düşünerek bunları yazsanız erişilebilirlik ciddi biçimde artar. Bir projeye yıllarınızı vermiş olsanız bile, kullanıcıların aradığını bulduğunu bile fark etmeden sırf uğraştırdığı için vazgeçtiği durumların tekrarlanması gerçekten üzücü. Ayrıca farklı doküman türlerinin rollerini iyi anlamak da önemli. https://diataxis.fr/ bunun için iyi bir başlangıç noktası
Dokümantasyon yazarken en önemli şey, hedef okuyucunun bilgi seviyesini net biçimde belirlemektir. Taban çizgisini yüksek ya da düşük tutmanız fark etmez; ama bu taban seviyeden fazla saparsanız bazı okurlar mutlaka memnuniyetsiz olacaktır. Böyle durumlarda ya bahane üretirsiniz ya da çözüm ararsınız. Gerçi bugünlerde AI, Google, kitaplar vb. ile her şeyi anında bulmak mümkün. "Shoobababoo nedir" ya da "neden quagmire kullanılıyor" diye merak eden biri aratabilir. Elbette ideal olan, dokümanın mümkün olduğunca dış kaynağa ihtiyaç duymadan kendi kendine yeterli olmasıdır; ama dünya her zaman bu kadar cömert değil
Uzun yıllar mentorluk yaparken vurguladığım ilke şuydu: "Bildiğini paylaşmak en iyisidir." Bir şeyi biliyorsanız mutlaka açıklayın; eğer zaten bilen birine söylemişseniz en fazla onun güvenini tazelemiş olursunuz, bilmiyorsa da büyük fayda sağlarsınız. Bazen fazla uzun anlattığıma dair şikâyet geliyor ama "bunu belki bir yeni çalışan, müşteri ya da yönetici de görebilir; onlar için yazmıştım" deyince çoğu kişi anlıyor. Bu ilke geliştirme, raporlama, insan yönetimi dahil her alanda geçerli
Yakın zamanda Gitlab ile DigitalOcean Kubernetes üzerine uygulama deploy etmeyi denedim; ne işe yaradıkları açıklanmadan 3-4 tane üçüncü taraf aracı uygulamak gerekti ve komut satırına yazılacak isimleri ya da yolları da kendim bulup doldurmam beklendi. Neyin referans olduğu ve neyin neye uyması gerektiği de anlatılmıyordu. Docker konusunda epey yetkin olmama rağmen bu araçların dokümanları o kadar kullanışsızdı ki, neredeyse hiç olmasalar daha iyiydi
Kitap yazmayı bırakıp tutorial web sitesi yapmamın ana nedeni, tutorial'ları daha erişilebilir kılmak için çeşitli interaktif araçlardan (
<abbr>öğesi gibi) yararlanabilmekti. Buna rağmen bugün web içeriğinin hâlâ kâğıt kitabın imkânlarında takılı kalması sinir bozucu. Tıklama, hover, bölüm katlama, video, kullanıcı etkileşimi gibi sayısız olanak var ama hâlâ duvar gibi uzun metinler görüyoruz. Hatta OP bile dipnota tıklayınca sayfanın en altına kaydıran bir yöntem kullanıyor; bu da web'in potansiyelini tam kullanmıyormuş gibi hissettiriyorAslında tutorial'ların çoğu ne geliştirici olmayanlara ne de geliştiricilere hitap ediyor; gereksiz uzun metinlerin arasına sıkışmış ve sonunda önemli bir iki adımı atlayan şeylere dönüşüyorlar. Bunun en büyük nedeni, insanın yazarken karşısında birine anlatıyormuş gibi ifade kurmasının zor olması. Zihninizde bildiğiniz bir şeyi yazıya dökmezseniz, okuyucu onu asla bilemez. "Tutorial" yerine daha çok "cookbook" tarzında yazmak, hem pratik kullanım için daha elverişli olur hem de sürüm yükseltmelerinden sonra tümüyle işe yaramaz hale gelmesini önler