Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- Matplotlib
- Teknik yazar:
- jeromev
- Proje adı:
- Matplotlib Giriş Yolları Geliştirme
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
Giriş
Matplotlib’in bu yılki Google Dokümanlar Sezonu için proje önerisi, Matplotlib'i yeni kullanıcılara tanıtmaya yardımcı olacak içerikler oluşturmayı içeriyor. Matplotlib Giriş Yolları Geliştirmek için mevcut belgelere alternatif bir yaklaşım öneriyorum. Sektöre yeni katılan bir teknik yazarım ancak eğitim ve eğitimle ilgili alanlarda geçmişim var. Teknik yazım ile eğitim, empati kuran ve kullanıcıların, sağlanan kaynaklarla görevlerini tamamlamasına olanak tanıyan içerikler üretmeye odaklanan güçlü benzerliklere sahiptir.
Bu bağlamda, Matplotlib dokümantasyonunun yeni kullanıcılarla empati kurmayı sağlayacak şekilde iyileştirilmesi faydalı olacaktır. Şu anda materyallerin çoğu rastgele verilerden ve etiketlenmemiş görsellerden oluşuyor. Bu videolar, Matplotlib'in görsellerini ve özelliklerini hızlıca göstermek için mükemmeldir. Ancak Matplotlib'i yeni kullanmaya başlayan bir kullanıcının verilerin görsellere dönüştürülmesini öğrenmesi zordur.
Açıklayıcı bir yaklaşımda bağlam, bu engeli aşmanın bir yoludur. Gerçek hayattan bir örnek üzerinden bir prosedür yazarak, kullanıcının çalıştığı ortamın anlaşılmasını gösteriyoruz. Bu, bir hedefe ulaşma veya bir görevi tamamlama beklentisi açısından dokümanların kullanıcıyla olan ilişkisini iyileştirir.
Kullanıcının, türetilmiş tutarlı bir amacı vardır. Örneğin, bir ayakkabı şirketindeki veri bilimci, zaman içindeki alışveriş trendlerini göstermek için müşteri verilerini bir ekibe sunmalıdır. Bu durumda, kullanıcının Matplotlib'te gezinmeyi öğrenmesi ve kitaplıktaki araçlardan yararlanarak elindeki görevi tamamlaması gerekir.
Dokümanları destekleyen ek bağlam sayesinde yeni kullanıcılar konuyla daha iyi ilişki kurabilir. Kullanıcının türetilen amacı, dokümanlara paraleldir. 2017'de yapılan bir röportajda Kıdemli Geliştirici Tom Caswell'in "Gerçekten yazabilen ve kullanıcılara karşı empati sahibi olan birinin, 200 sayfalık bir "Matplotlib'e Giriş" kitabı yazması ve bu kitabın dokümanlara ana giriş olması" şeklinde belirttiği vizyona ulaşmak için çalışmayı umuyorum.
Temalı Yazmada Alternatif Yaklaşım
Mevcut belgeler Matplotlib'in özelliklerini, yani kullanıcının kitaplıkla neler yapabileceğini gösterir. Örneğin, bir eğitimde genellikle temel yöntemin açıklanmadığı bir kalıp izlenir.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
Programlama dokümanları ve desteklerinde, kullanıcının ne olduğunu anlamak için kodu kendi başına çalıştırması genellikle önerilir. Programlama zihniyeti, kullanıcının konuyu anlamasını iyileştirmesine rağmen dönüşümler için öğrenme eğrisinde çok az destekleyici içerik vardır. Belgeler sınırlı olduğu için bu, çok zor bir süreç olabilir.
Ek diyagramlar, resimler veya başka görseller ekleyerek yeni öğrenme fırsatları oluşturabilirsiniz. Aşağıdaki yapı, yeni içerikler için şablon olarak da kullanılabilir. Ayrıca, metin içermeyen resim veya grafik eklemenin amacı, açıklama metinleri ve eğitim işaretleri gibi özelliklerden yararlanmaktır. Kodun nasıl veya nerede çalıştırılan çıktıya dönüştürüldüğüne dair göstergeler olmadan resimlerde gezinmenin daha zor olduğu durumlar vardır. Konuların daha iyi anlaşılmasını sağlayacak güçlü bir görsel öğe eksik.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
Dokümanlar için açıklayıcı yazım kullanmaya yönelik bu alternatif yaklaşımda büyük bir potansiyel var. Kullanıcılar dönüşümlerle ilgili çeşitli kavramlar gördüklerinde, verilere yönelik görselleştirmeler geliştirmenin temel stratejilerini daha iyi belirleyebilirler. Bu bilgi, kullanıcıların yenilik yapmalarına ve gerçekçi kullanım alanlarına dayalı örneklerle sunulan özelliklerden yararlanmalarına yardımcı olabilir.
Matplotlib'in popülaritesi arttıkça kullanım kolaylığı ve erişilebilirlik açısından tutarlılığı, kitaplığın itibarını kanıtlıyor. Bu özellikler, yalnızca kodun içinde değil, aynı zamanda belgelerde de ortaya çıkabilecek kalıpları ve yaygın stratejileri ortaya koymaya yardımcı olur. Matplotlib, kullanıcıların programlaması için basit ve standartsa (artan kullanımı ve genişleyen kaynaklarıyla görüldüğü gibi) teknik dokümanlar için de bu şekilde olabilir.
Kullanıcılar sorunla karşılaştığında bu sorunları çözmek için aramayı kullanırlar. Gezinme için birincil yöntem olarak arama kullanmak yerine, kullanıcıların dokümanları içinde kendi müfredatlarını oluşturmalarını sağlamak daha etkili olabilir. Bu bağlamda, kullanıcılar sorunlarına çözüm arar, ardından başka bir sorunla karşılaştıklarında veya ek bilgi istediklerinde, yerleşik ve kapsamlı bağlantılardan yararlanır.
Bu, kuruluş sisteminde aşağıdan yukarıya bir mimari gerektirir. Matplotlib'deki her konu için konu yakınlıklarına ve bilgi dokümanlarına bağlantılar içeren zengin bir ağ oluşturmak güçlü bir ağ oluşturmanıza yardımcı olur. Bu ağda, kullanıcılar ilgilendikleri konuya gidip konuyla ilgili daha fazla bilgi keşfederken dokümanları kullanmaya devam etme olasılıkları daha yüksektir.
Engeller
Bu kadar kapsamlı ve ayrıntılı bir projede her zaman zorluklar yaşanır. Sektörde yeni bir teknik yazar olarak, doküman yazmak için Sphinx ve ReST'i kullanma konusunda sınırlı deneyimim var. Matplotlib ve Git konusunda da yeniyim. Bu dört sistemi ele almak ve bunları ortak çalışma ve araştırma için kullanmaya alışmak zaman alacak. Giriş seviyesi yollar için gerekli temeli oluşturmak amacıyla, topluluk bağları oluşturma aşamasında ve öncesinde zaman ayırmam gerekiyor. Bu süre zarfında kavramlar ve temel bilgiler konusunda sorun yaşarsam ek destek için toplulukla iletişime geçmem gerekecek.
Farklı saat dilimlerinde ve online platformlarda ortak çalışma çabalarını koordine etmek de biraz düzenleme gerektirir. Sektördeki herkesin kullandığı çeşitli iletişim kanalları var. Bu nedenle, tüm platformlarda ulaşılabilir ve samimi olmaya çalışıyorum. Proje süresi boyunca farklı beklentilere öncelik verirken şeffaf olacağım. Sektörde bu tür işler almaya yeni başlamış olsam da kendimi sorumlu tutmaya ve geri bildirim ile eleştirilere açık olmaya çalışıyorum. Bu özelliklerin, hangi alanda olursanız olun değerli olduğunu düşünüyorum.
Ayrıca, kullanılabilirlik testlerini artırmanın, Matplotlib'in giriş yollarına fayda sağlayacağını düşünüyorum. İçerikle ilgili kullanılabilirlik anketleri yapmak, kullanıcı profilleri (personalar) oluşturmak için yararlıdır. Kullanıcının deneyimi, çalıştığı sektör ve sorun giderme geçmişi gibi bilgiler değerlidir. Bu parçalar, prosedürün temelini oluşturan dili oluşturmaya yardımcı olur. Yazdığınız içerikler okuyucuların seviyesine uygun olduğunda, içerik yalnızca eğitici olmaktan çıkar.
Yaşanan büyük zorluklar genellikle kullanılabilirlik testinin sürekli olarak yürütülmesinden kaynaklanır. İçerik geliştirme sırasında tek bir test örneğinin yapılması (testin hiç yapılmaması da yaygındır) çok yaygın bir durumdur. Düzenli kullanılabilirlik testleri, içeriğin anlatımına katkıda bulunur. Bir program ayarlamayı veya Matplotlib topluluğuyla yinelenen kullanılabilirlik testleri yapmayı umuyoruz.
Sonuç
Boş zamanlarımda Python ve Matplotlib kullanımı konusunda biraz deneyimim oldu. Son birkaç ayda kendime öğrettiğim şeylerden biri, mevcut belgelerin desteğiyle ve merakımla ilgilenmemdi. Bu süreçte izlediğim birkaç video ve danışmandan da yararlandım. İlgilendiğim programlama konularını içeren kendi müfredatımı oluştururken hâlâ öğrenecek çok şeyim ve daha da iyiye gitmeye dair daha fazla alanım var.
Matplotlib ve topluluğun GSoD için sahip olduğu fikirleri gördükten sonra, teknik yazar olarak becerilerimi geliştirmek ve perde arkasındaki kişilerden daha fazla bilgi edinme fırsatı elde etmek için bu deneyimin mükemmel bir gelişim fırsatı olacağını düşünüyorum. Bu Matplotlib projesinin hem anlamlı hem de ideolojik açıdan tutkulu olduğumu hissettim.
Kullanım kılavuzunun kapsamlı bir şekilde yeniden düzenlenmesi üzerinde çalışan teknik yazar olarak amacım, kullanıcıların mevcut özelliklerden bunalmamak için istedikleri görevleri tamamlamalarına yardımcı olmaktır. En iyi belgelerin gelişmeye, kullanıcılara ve kullanıcıların kendi çözümlerine ulaşmasına olanak tanımaya devam edeceğine inanıyorum.