- esbuild ve Redis, olağanüstü dokümantasyona sahip kod tabanlarına örnek teşkil ediyor.
- README, değişiklik günlüğü, mimari dokümanları ve kod yorumları sayesinde yeni kullanıcılar da kod tabanının yapısını, nasıl çalıştığını ve neden böyle tasarlandığını anlayabiliyor.
- Kod ve yazılım mimarisi dokümantasyonunu iyileştirmek isteyen geliştiriciler için iyi birer vaka incelemesi niteliği taşıyor.
İyi dokümantasyon neden önemlidir
- Yazılım geliştirirken, özellikle başkaları kod tabanını inceleyecek veya katkıda bulunacaksa ya da siz daha sonra tekrar dönüp bakacaksanız, iyi dokümantasyon vazgeçilmezdir.
- Yazılım kullanıcıları çoğu zaman eksik dokümantasyon nedeniyle zorlanır.
- Bir kod tabanına katkıda bulunuyorsanız, dokümantasyonun kalitesi ne kadar yüksekse o kadar hızlı katkı verebilirsiniz.
- Dokümantasyonun kalitesi; yazarın, katkı sağlayanların ve kullanıcıların deneyimini doğrudan ya da dolaylı olarak etkiler.
- İyi dokümantasyonun faydaları arasında zaman tasarrufu, açık kaynak projelerine dış katkının artması, geçmiş kararların kayda geçirilmesi, daha fazla kullanıcı için erişilebilirlik, düşüncenin yapılandırılması ve sorunların fark edilmesi yer alır.
esbuild'in dokümantasyonu
- esbuild, Evan Wallace tarafından geliştirilen bir JavaScript bundler'ıdır.
- esbuild'in README dosyası, aracın son kullanıcılarına odaklanır.
- Dokümanın ana bölüm bağlantıları ve "Neden?" bölümü aracılığıyla, neden diğer bundler'lar yerine esbuild'in tercih edilmesi gerektiği kısaca açıklanır.
- esbuild'in mimari dokümanları,
docs dizinindeki architecture.md ve development.md dosyalarından oluşur.
- Mimari dokümanları tasarım ilkelerini açıklar ve yalnızca metin değil, kavramları anlatan görseller de içerir.
- esbuild'in değişiklik günlüğü; özetler, genişletilmiş açıklamalar ve değişiklik öncesi-sonrası örnek kodlarla ayrıntılıdır.
Redis'in dokümantasyonu
- Redis, bellek içi bir veritabanıdır.
- Redis'in README dosyası, esbuild'inkine benzer güçlü özellikler taşırken hem katkı sağlayanlara hem de son kullanıcılara odaklanır.
- Redis'in iç yapısına ayrılan bölüm, kaynak kodun yerleşimi ve temel dosyaların açıklamalarını içerir.
- Redis kaynak kodundaki yorumlar, tek bir kod satırı için bile birden fazla paragraf uzunluğunda açıklamalar sunar.
Sonuç
- Pek çok açık kaynak projesi mükemmel dokümantasyona sahiptir.
- esbuild ve Redis, özellikle etkileyici dokümantasyonlarıyla öne çıkar.
- Dokümantasyon kısa vadede zaman baskısı yaratabilir, ancak uzun vadede zaman kazandırır.
- Çok sayıda kişinin kullandığı veya katkı verdiği projelerde dokümantasyon yapmamak, yeniden düşünülmesi gereken bir konudur.
GN⁺ görüşü
- esbuild ve Redis'in dokümantasyon örnekleri, geliştiricilere kod tabanını anlama ve bakımını kolaylaştıran dokümantasyonun önemini güçlü biçimde gösteriyor.
- Dokümantasyon, projenin sürdürülebilirliğini artıran ve topluluk katılımını teşvik eden temel unsurlardan biridir.
- esbuild özelinde, hızlı bir JavaScript bundler'ı olmasının yanı sıra güçlü dokümantasyonunun da projenin büyümesine katkı sağladığı görülüyor.
- Redis ise karmaşık bir bellek içi veritabanı sistemini daha kolay anlaşılır kılan dokümantasyonu sayesinde geliştirici topluluğu üzerinde olumlu bir etki yaratıyor.
- Bu örnekler, diğer açık kaynak projelere de dokümantasyonun önemini aktarmaya yardımcı olabilir; özellikle de başlangıç seviyesindeki yazılım mühendislerinin kendi projelerini nasıl dokümante edeceklerini anlamaları açısından yararlıdır.
2 yorum
esbuild'in README.md dosyası da öyle ama yazıda tanıtılan architecture.md dosyası da gerçekten çok güzel!
Hacker News görüşü
Redis'in yaratıcısı Antirez, blogunda kod yorumları hakkındaki düşüncelerini ayrıntılı biçimde anlattığı bir yazı yazmış. Redis'te kullanılan 9 tür yorumu tanımlıyor.
Proje dokümantasyonunun kullanıcılar/geliştiriciler/katkı sunanlar için nasıl mükemmel olabileceğine dair somut örnekler ve ekran görüntüleri içeren iyi yazılmış bir makale.
Depo kalitesine yöneticilerin önem verdiğini gösteriyor.
"The Architecture of Open Source Applications" serisini hatırlatıyor. İlginç içgörüler içeriyor.
GitLab'in dokümantasyonunun çok iyi olduğuna dair bir itibarı var, ancak bunu doğrudan kullanma ihtiyacı fazla olmamış. Mimari dokümantasyonlarının da iyi olup olmadığı merak ediliyor.
Postgres projesi de dokümantasyona, readme dosyalarına ve kod yorumlarına ayrıntılı özen gösteriyor.
esbuild projesinin mimari dokümantasyonundan derinden etkilenmiş. Geçmişte üzerinde çalıştığı kod tabanlarında böyle belgeler olmasını isterdi.
Açık kaynak projelerin değişiklik günlüklerini çok seviyor. Kâr amacı güden diğer oluşumlara kıyasla çok daha profesyonel ve bilgilendirici buluyor. ING Bank'ın uygulama değişiklik günlüğünün esprili olmaktan çok bilgi vermeye odaklanması gerektiğini eleştiriyor.
"Bugün özgür yazılım topluluğundaki en büyük eksiklik yazılım değil, özgür yazılımla birlikte sunulabilecek iyi özgür dokümantasyonun eksikliğidir."
Redis'in artık açık kaynak olmadığını belirtiyor. Redis, Redis Source Available License v2 (RSALv2) ve Server Side Public License v1 (SSPLv1) kapsamında "source-available" bir yazılım.