Örnekler en iyi dokümantasyondur

 (rakhim.exotext.com)
38 puan yazan GN⁺ 2025-10-11 | 8 yorum | WhatsApp'ta paylaş
  • Geliştiriciler dokümantasyon aradığında vakaların %95’inde yalnızca basit bir örnek yeterlidir, ancak resmi kaynaklarda örnek bulunabilen durumlar sadece %5’tir
  • Resmi teknik dokümanlar temelde o ekosisteme derinlemesine dalmış kişileri hedef alacak şekilde yazılır; bu da farklı projeler ve diller arasında gidip gelen geliştiriciler için bağlamı yeniden kurmak adına ciddi bir zihinsel enerji gerektirir
  • Python’un max() fonksiyonu dokümanına bakıldığında, fonksiyon tanım sözdizimini ve kavramları anlamak için gereken ön bilgi fazladır; oysa 5 satırlık basit bir örnekle anında anlaşılabilir
  • Clojure topluluğunun clojuredocs.org sitesi, kullanıcı katkılı örnekler aracılığıyla pratik dokümantasyon sunar ve ilgili fonksiyonları da içererek gerçek kullanım değerini artıran örnek bir yaklaşım sergiler
  • Büyük yazılım projelerinde bile 4 tür dokümantasyonun bir arada sunulması nadirdir; bu yüzden geliştiriciler tutorial arar, çünkü ihtiyaç duydukları şey yönlendirme değil, örnektir

Dokümantasyon ararken örneklerin önemi

  • Geliştiriciler doküman aradığında vakaların %95’inde tek bir örnek yeterlidir
  • Ancak resmi kaynakta örnek bulabildikleri durumlar sadece %5’tir
  • Resmi teknik dokümanların çoğu varsayılan olarak ekosisteme derinlemesine hâkim kişileri hedefler
  • Birçok geliştirici günlük olarak zihninde birden fazla “dünya”yı jonglör gibi çevirmek zorundadır
    • Projeler, diller ve framework’ler arasında sık geçiş olur
    • Bağlamı yeniden kurmak ve durumu anlamak için kayda değer zihinsel enerji harcanır

Python dokümantasyonu örnek analizi

  • Python 3 dokümanındaki max() fonksiyonu örneği
    • max(iterable, /, *, key=None): en büyük öğeyi döndürür
    • Ardından 5 kısa paragrafla açıklama devam eder
  • Bu dokümanı anlamak için bilinmesi gereken Python bilgileri
    • Fonksiyon tanımında * işaretinin anlamı
    • Fonksiyon tanımında / işaretinin anlamı
    • “positional-only parameter separator” kavramı
    • iterable kavramı
    • keyword-only arguments kavramı
    • key parametresinin genel anlamı
  • Metni okumadan hangi değerlerin verileceğini ve fonksiyonun pratikte nasıl çağrılacağını anlamak zordur

Basit örneklerin etkisi

  • Önemli ayrıntıların özlülük uğruna çıkarılamayacağı kabul ediliyor
  • Ancak birçok geliştiricinin o sayfayı bulma nedeni, yalnızca max fonksiyonuna özel bir sıralama fonksiyonunun (key) nasıl verileceğini hızlıca görmek istemesidir
  • Aşağıdaki gibi örnekler olsa istenen bilgiye hemen ulaşılabilir 
    max(4, 6) # → 6  
max([1, 2, 3]) # → 3  
max(['x', 'y', 'abc'], key=len) # → 'abc'  
max([]) # ValueError: max() arg is an empty sequence  
max([], default=5) # → 5
  • Örnekler sayesinde kolay ve sezgisel biçimde anlaşılabilir

Clojure topluluğundan örnek bir yaklaşım

  • clojuredocs.org, Clojure topluluğu temelli bir projedir
    • Kullanıcılar yerleşik fonksiyonlara örnek katkısı yapar
    • Günlük yazılım geliştirmede vazgeçilmez bir kaynak işlevi görür
  • Örnek sayfalar: into, spit, map
  • Örneklerin özellikleri
    • Yalnızca ilgili fonksiyonu değil, ilişkili fonksiyonları da içerir
    • Gerçek kullanım değerini ve pratikliği artırır

Güncel dokümantasyonun sınırları

  • Büyük yazılım projelerinde bile 4 tür dokümantasyonun birlikte sunulması nadirdir
  • “Documentation” bağlantısına tıklamayı tereddüt ettiren neden
    • Çoğu zaman karşılaşılan şey kısa ama okunması zor, otomatik üretilmiş API referanslarıdır
  • Geliştiricilerin tutorial aramasının asıl nedeni
    • Yönlendirmeye ihtiyaç duymaları değil, örneğe ihtiyaç duymalarıdır
    • Tutorial’lar örnek içerdiği için daha faydalıdır

İlgili okumalar

8 yorum

 
sonnet 2025-10-12

Açıkçası bunun daha çok Java ve Python merkezli bir söylem olduğunu düşünüyorum. Burası aynı zamanda kendi dilini üstün gören anlayışın ya da paradigma açısından izole bir kültürün güçlü olduğu bir ekosistem de. Python açısından bakınca anlatılanlar yerli yerine oturuyor ama çeşitli dilleri çalıştıkça o %5 bana epey abartılı gelmeye başlıyor.
 
kuber 2025-10-12

Kodun bizzat dokümantasyon olduğu Go dünyasına gelin~
Biz README olmasa da test kodunu kurcalayıp geliştiriyoruz
 
pjtco 2025-10-11

Resmî dokümanı anlayamayan tek aptal ben sanıyordum lol
Gerçekten ortaya bir örnek atıp üstüne birazcık açıklama yapınca hemen anlaşılıyor.....
 
nemorize 2025-10-11

PHP hem iyi bir örnek hem de en kötü örnek sayılır sanırım.

Resmî dokümantasyona kullanıcı katkılı içerik yüklenebildiği için çeşitli kod örneklerini görebilme açısından iyi bir örnek oluyor,

...ama PHP'nin yerleşik fonksiyonlarında ince BC uyumsuzlukları çok fazla ve o örnek katkılarının hepsi de adeta tarihin tozlu raflarından kalma sürümlere ait olduğundan, gerçek çalışmayla ince farklar gösteren şeyler birbirine karışıp sadece kafa karışıklığını artırıyor... hahaha.. keke ...
 
savvykang 2025-10-11

Eski iOS ya da Cocoa geliştirme belgelerine bakınca use case bölümü ayrı olurdu; doğru belgeleme yöntemi de bu değil mi? Örnekler, fonksiyon imzaları ve davranış açıklamalarının hepsi gereklidir.
 
aer0700 2025-10-11

Eskiden resmi docs'un yetersizliğini Stack Overflow ve Google aramaları kapatıyorsa, bugünlerde bunu LLM'lerin kapattığı anlaşılıyor.
 
GN⁺ 2025-10-11
Hacker News görüşü

  • Eski Python’ın en iyi yanlarından biri, kütüphane belgelerini açtığınızda fonksiyonun argümanları ve dönüş değerlerinin açıkça düzenlenmiş olmasıydı. Günümüzde birçok JavaScript ya da Python kütüphanesi belgesinin yalnızca örnek sunması üzücü. Hızlıca bir şeyler geliştirmek için örnekler iyidir ama bir sorunu düzeltmek ya da kütüphaneyi öğrenmek için argüman açıklamaları şarttır. Örneklerin bonus olması güzel ama sadece onlardan ibaret olmamalı

    • Aslında istediğiniz şey tip tanımları. Tip tanımları iyi bir belgeleme işlevi görüyor. Tip sistemi araçları zaten birçok bilgiyi editörde ya da IDE’de doğrudan gösterdiği için ayrıca belge arayıp okuma ihtiyacı azalıyor. Bugünlerde örnek odaklı belgelerin artmasının nedeni de iş akışındaki bu değişim. Zaten tip araçlarının vereceği bilgiyi belgede tekrar yazmaya gerek olmadığı düşünülüyor. Ben belgeye baktığımda ayrıntılı argümanlardan çok, “bu araç benim hangi problemimi çözebilir?” sorusuyla ilgileniyorum. Örnekler bu olasılığı göstermede mükemmel. Belirli bir problemi çözmek istediğinizde, örneğe bakıp bu aracın yardımcı olup olmayacağını hızlıca anlayabilirsiniz. --- Tip sistemi varsa ben önce örneklere bakmak isterim. Tip sistemi yoksa 1) memnun olmam. 2) önce örneklere bakar, ardından ayrıntılı argüman/dönüş/veri yapısı açıklamalarını isterim

    • İyi belgede ikisi de gerekir. Önce ayrıntılar açıklanır, sonra da farklı örneklerle bunlar doğrulanabilir. Bazen sadece örnekler yeterli olabilir ama seçenek kombinasyonları çok fazlaysa hepsini örneklerle göstermek neredeyse imkânsızdır. Bu yüzden önce her seçeneğin açıklamasını vermek, sonra da okuyucunun uyarlayabilmesi için olabildiğince çeşitli örnekler hazırlamak gerekir. Ayrıca iyi belge hazırlamak çok zordur ve bugünlerde gerçekten nadir görülür

    • Tam olarak katılmıyorum. Javadoc tarzı belgeler, tipler ve satır içi docstring’lere dayalı programlama belgeleridir. Kesinlikle gerekli ama bunun için illa web’e gitmek yerine kodun kendisine bakmak daha verimli. Örnekler ya da QuickStart gibi kılavuzlar ise kesinlikle gerekli. Bunlar kütüphaneye giriş eşiğini düşürüyor. Sadece koda bakarak API’nin nasıl kullanılacağını anlamak kolay değil. Geçmişte birçok Java kütüphanesinin yalnızca Javadoc sunması yüzünden nasıl kullanılacağını bilemeyip zorlandığım olmuştu

    • İyi yorumlanmış örneklerin en iyisi olduğunu düşünüyorum. Ama geleneksel belgenin yerini tutamazlar

    • Başkalarının sizden farklı bir öğrenme stiline sahip olabileceğini hiç düşündünüz mü? Örneklerin belgenin bir parçası olmasına neden direnç gösterildiğini anlamıyorum. Çünkü örnekler, çeşitli durumlarda bağlam değiştirme sürtünmesini azaltıyor

  • Unix man sayfalarının da örneklere ciddi şekilde ihtiyacı var. Genellikle zaten aracı iyi bilen kişiler için bir referans olarak yazıldıklarından yeni başlayanlara hiç yardımcı olmuyorlar. İyi belgede iki taraf da olmalı

    • Kesinlikle katılıyorum. Tüm man sayfası yazarlarına, geleneksel bölümler arasında EXAMPLE diye bir bölüm bulunduğunu hatırlatmak isterim. resmî man(1) belgesine bakılabilir

    • Ben böyle bir sorun hiç yaşamadım. Önce bir şeyler yapmaya çalışırken komutları ve terimleri öğreniyor, sonra hata dönüş kodlarına, nedenlerine ve parametrelerin anlamına tek tek bakıyorum. Örnek olmasa da belge tam ise bu yeterli. Buna karşılık, hiçbir açıklama olmadan yalnızca örnek verilmesi gerçekten en kötüsü. Parametrenin ne olduğu, ne anlama geldiği bile belli olmayan belge mi olur?

    • Stack Overflow’un da geçmişte benzer bir girişimde bulunmuş olması hoşuma gitmişti. Stack Overflow Documentation adıyla 2016’dan 2017’ye kadar beta olarak yürütülmüştü. Örnek merkezli belge üretmeye çalıştılar ama kapatıldı. Yine de topluluğun bıraktığı içerik hâlâ CC BY-SA olarak açık

    • cheat.sh’ye bakabilirsiniz. Ben bunu betiklerde doğrudan curl cheat.sh/"$1" ile kullanıyorum

    • Şaşırtıcı biçimde çok sayıda man sayfasında örnekler olduğuna hep şaşırırım. Yine de daha kapsamlı iyileştirme için alan var

  • Örnekler yalnızca yeni başlayanlar ya da ara sıra kullananlar için iyi değildir. Uzman kullanıcıların da tüm parametre yapılandırmalarını içeren düzenli belgelere ihtiyacı vardır. Örneğin requests belgelerinde Google sizi hep Quickstart gibi örnek dolu sayfalara yönlendiriyor ve bu can sıkıcı. HTTP GET’i herkes biliyor ama diğer seçenekler neler, timeout nasıl işliyor ya da raise_for_status 204’ü yok sayıyor mu, bunları bulmak zor. İkisi de gerekli ama geliştirici zamanı kısıtlıysa ben önce doğru referans belgesini sunmayı seçerim. requests Quickstart örnek bağlantısı

    • Örneklerde davranışı, referans tarzı belgelere kıyasla çok daha kolay anlayabilirsiniz. İnsanlar hem isim koymada hem kavramları düzenlemede hem de belge yazmada zayıf. Yakın zamanda da bir parametrenin yalnızca belli koşullarda çalışması yüzünden saatler harcadım. Kodu anlamaya çalışmak fazla karmaşıktı, hatta LLM bile bu parametrenin belgelenmediğini yanlış söyledi. Sonunda örnek kodlar yazarak istediğim davranışı bulmak en verimli yol oldu. Örnekler, birçok önemli bilgiyi sıkıştırıp hızlıca doğrulamayı sağlar. Buna karşılık API belgeleri her şeyi kapsamak istediğinden hem yönetmesi zor olur hem de özeti veremez. Ayrıca açıkça belirtilmedikçe bir kütüphanenin davranışına asla güvenmem. README’de açıkça gösterilmiyorsa ya da tiplerle tanımlanmıyorsa bunun her an değişebileceğini varsayarım. Sonuçta çağrı kodunu olabildiğince savunmacı yazarım

    • Örnekler yalnızca yeni başlayanlar için değil, herkes için önemlidir. 5 saniyelik bir örnekle bir saatlik belge okuma ve deneme verimi elde edebilirsiniz. Git’in bazı belgelerinde bu özellikle geçerli; özünde basit ama açıklaması zor fonksiyonlar için de aynı şey geçerli. Geliştirici sadece tek bir şey üretebilecek olsa bile, hem örnek hem belge koyabilecek kadar imkânı vardır. İkisi de sunulmalı; ancak çok bariz durumlar istisna olabilir

    • Katılıyorum. İyi belge neredeyse programın tüm davranışını açıkça tanımlamalı; bunu yalnızca örneklerle yapmak zordur

    • İkisine de aynı anda sahip olabilirsiniz. Örnekler ve teknik belgeler birbirini dışlayan şeyler değil

    • occasional users derken tam olarak bunu kastediyorum. Projeler, diller ve framework’ler arasında geçiş yaptıkça bağlamı yeniden kurmak ve ne olup bittiğini anlamak ciddi bir zihinsel maliyet yaratıyor

  • Perl hakkında ne derseniz deyin ama Perl belgeleri gerçekten yardımcı oluyor. En başta her zaman bir SYNOPSIS bölümü oluyor ve doğrudan kullanılabilecek örnek kod veriyor. Ardından açıklamalar, referanslar ve ek örnekler geliyor. Örnekler: bigrat belgesi, Archive::Tar belgesi. Proje belgesi yazarken Perl tarzına bakmak iyi olur. Üstelik bu tarzın kendisi de iyi belgelenmiş

    • 2000’lerin başında Perl kullanmıştım, sonra 2014’te tesadüfen tekrar kullandım ve sanki her şeyi yeniden hatırlıyormuşum gibi hissettirdi. Sanırım Larry Wall’un dilbilimsel bakış açısı ve tavrından ötürü çok akılda kalıcı. Matematiksel kesinlikten değil ama adeta “bir arkadaşla konuşuyormuşsunuz” hissi veriyor

  • İkisi de gerekli. Örnekler hemen fikir verir ve entegrasyonu kolaylaştırır; ayrıntılı parametre ve yapılandırma açıklamaları ise aracın karmaşık sorun çözümünü ve genel olarak anlaşılmasını destekler. Bunlardan biri eksik olursa gerçekten rahatsız edici olur. Yalnız, çok basit kütüphanelerde örnekler her şeyi açıklayabilir

    • Hem örnekler hem referans belgeleri gerekli. Mümkünse bir REPL ortamı da eklemek iyi olur. Örnekleri anında değiştirip test edebilirseniz, belgenin eksik olduğu birçok durumda bu açığı kapatabilirsiniz

  • Diátaxis çerçevesi, belgelerin farklı türleri olduğunu ve her birinin farklı amaçlara hizmet ettiğini çok iyi gösteriyor. Hangisinin “en iyi” olduğu değil, farklı ihtiyaçlara göre kullanılması önemli. Diátaxis resmî sitesi

    • Bu yorum en üstte olmalıydı. Bunca tartışmadan sonra ancak Diátaxis’ten bahsedilmesi biraz sinir bozucuydu. Bana göre örnekler belgelemenin merkezinde yer alsa da başlı başına bir “belge türü” olmaktan çok önemli bir “belgeleme tekniği”

    • Aynen! Örnekler (ya da eğitimler) bir sistemi öğretmenin eksenlerinden biridir. Bunu ilk kimin ortaya attığından emin değilim ama bağlantı, yazının sonundaki yazarın bağlantısına benziyor: > “Büyük projelerde bile dört tür belgenin tamamına sahip olanlara nadiren rastlanır. Bu yüzden ‘Documentation’ bağlantısına tıklamakta tereddüt ettiğim oluyor.” Ben açıklama ağırlıklı belgeleri seviyorum. Yapıyı ya da neden böyle davrandığını anladığınızda örnekleri ve eğitimleri çok daha kolay özümsüyorsunuz. Usta teknik yazarlar ya da eğitimciler bu çerçeveyi en baştan iyi kurarsa çok etkili oluyor. Buna karşılık API referansları en çok wrapper ya da uyumlu uygulama geliştirirken gerekli oluyor. Zaten birçok proje başlangıçta özel API referanslarıyla başladı; belgeleme de bunların dışarıya açılmasıydı. Divio belgeleme sistemine bakılabilir

    • Diátaxis fikri harika. Ancak bunu gerçek projelere uygulamak kolay değil. Her projenin ihtiyaç duyduğu belge oranı farklı ve tüm biçimleri tek bir web sitesinde sunmak verimsiz olabilir. Topluluk büyüdükçe ve uzmanlaştıkça bu oranlar da sürekli değişiyor. Keşke daha pratik bir yöntem olsa. Belgeleme zor bir iş ve umarım bir gün daha iyi çözümler çıkar. Şimdilik kalite, ayrılan zaman ve uzmanlığa bağlı; ama çoğu zaman bunlar yetersiz kalıyor

  • Unity ve Unreal’da bu sorunu gerçekten çok sık yaşıyorum. Özellikle Unreal’ın node belgeleri bazen sadece node’un ekran görüntüsünü ve adını tekrar yazıyor, ama gerçekte nasıl kullanılacağını hiç anlatmıyor. Unity’de de bazen bir fonksiyonun düzgün kullanımını öğrenmek için belgeye gidiyorum ama içerik neredeyse yok oluyor. İmkân olsa ben bile Unity belgelerine örnek katkısı yapmak isterdim

    • Unreal’ın berbat belgelendirmesi benim için de inanılmaz bir zaman kaybı. Onlarda “kod belgedir” havası var ama Blueprint için sunulan “node ekran görüntüsü açıklaması” gerçekten gülünç düzeyde

    • £JOB konusunda, insanlar $job yazarken bunu gerçekten para kazandıran iş anlamında mı kullanıyorlar, yoksa sadece sıradan bir değişken adı olduğu için mi? Bu noktada dünya görüşüm sarsılıyor

  • Ben ImageMagick’i sık kullanıyorum ve hep örnek aramak için Google’da geziniyordum. Bu yüzden kendi notlarımı küçük bir komut örnekleri derlemesine dönüştürdüm. Her argüman için ayrıntılı açıklamalar da ekledim. Bu blog yazısındaki gibi yalnızca örnekler değil, açıklamalar da gerektiğini düşünüyorum. Hâlâ taslak aşamasında ama yeniden boyutlandırma, optimizasyon, katmanlama gibi günlük işler için şimdiden çok faydalı. Notlarımın açık bağlantısı

  • Kod örnekleri birim testleriyle çalıştırılarak belgenin eskimesi ya da bozulması önlenebilir. Bu, doğal dilde mümkün olmayan bir avantaj

    • Artık LLM’ler geliştikçe, örneğin API belgelerinin doğruluğunu da doğrulamaya yönelik denemeler yapılabilir

  • Radikal görüş: Belirli bir metodun sözleşmesi, imzasına ve birkaç tipik örneğe bakınca sezgisel olarak çıkarılamıyorsa, o metod muhtemelen fazla şey yapmaya çalışıyordur. Ayak bağı olan soyutlamaları ya da karmaşık istisnaları da öğrenmek istemiyorum

    • Katılmıyorum. Örnekler sadece o metodun kendisini değil, “diğer metodlarla birlikte nasıl kullanılması gerektiğini” göstermek için de gereklidir. Metod imzasından her şeyi çıkarabiliyor olsanız bile, kurulum eksikleri, hazırlık adımları ya da sonuç işleme gibi önemli noktaları kaçırmak kolaydır. Bu yüzden örnekler şarttır
 
howudoin 2025-10-11

Java ekosistemi ve nesne yönelimli kültürde özellikle anlamsız açıklama cümleleriyle biçimsel dokümantasyon çoktu; o havayı devralan Python ekosistemindeki framework'lerde de örnekler özellikle zayıf.

Anlamsız dokümantasyona örnek
add(left, right) - sol ve sağ girdiyi toplar

Asıl önemli olan parametrelerin veri tipi, dönebilecek istisnalar, sonuç değerinin biçimi ya da çalışma yapısı gibi şeyler ise açıklanmıyor.

C dilindeki man page'ler gibi olsa, sadece kısa bir açıklamayla bile fonksiyon ve parametre adlarından çıkarım yaparak kullanılabilir.