Bu sayfa, Google Dokümanlar Sezonu için kabul edilen teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- SciPy
- Teknik yazar:
- mkg33
- Proje adı:
- Kullanıcı odaklı belgeler ve kapsamlı bir yeniden yapılandırma
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Motivasyon:
Mevcut dokümanları, farklı ihtiyaçları olan kullanıcıların kolayca erişebileceği şekilde yeniden düzenleme üzerinde çalışmayı planlıyorum. Söylemeye gerek var diyebiliriz, araştırmacı büyük olasılıkla gelişmiş ve kolayca fark edilmeyecek özelliklere ilgi gösterirken, önceden uzmanlığa sahip olmayan bir kullanıcı adım adım açıklamalı kılavuzlara ve diyagramlara çok önem verir.
Bu projeyi kişisel ve profesyonel nedenlerle yürütmeyi istiyorum: Öncelikle, SciPy'ye önemli ölçüde katkıda bulunmak istiyorum, çünkü kendi araştırmam çok faydalı oldu. İkincisi, diğer yazılımlarda yetersiz (veya eksik) belgelerle çok sık karşılaşıyorum ve kullanıcılara kapsamlı bir kılavuz sağlanmış olsa bile kodu ne kadar daha hızlı öğrenebileceklerini merak ediyorum.
Hedefler:
Mevcut SciPy belgelerini hem içerik hem de grafik açısından iyileştirmeyi amaçlıyorum. Bu soruna yaklaşımımın en önemli özelliği, kullanıcı anketinin dağıtılması ve analiz edilmesidir. Bir başka deyişle, çeşitli kullanıcıların dokümanlara ilişkin ihtiyaçlarını dile getirmelerini sağlayan, çevrimiçi olarak yürütülen kısa ve öz bir anket hazırlanır. Fikirlerinin ilham kaynağı olması gerektiğine yürekten inanıyorum (başka nasıl daha kullanıcı dostu bir doküman oluşturabiliriz?).
Projenin gerçekleştirilmesine gelince, ilk aşamada kullanıcı anketinin tasarlanması ve analiz edilmesi gerekir. Ayrıca, mevcut belgede gördüğüm biçimsel bazı sorunlar ele alınır. Örneğin, tutarlılık eksikliği (örneğin: iki boyutlu dizilerin yanında yer alan 2 boyutlu diziler), yeniden yazılması gereken kıvrımlı cümleler veya belirli alt sayfalarda alfabetik sıranın eksikliği. İkinci aşamada, alakalı konulara bağlantılar içeren grafik kılavuzların sunulmasına odaklanılacaktır (anket sonuçları ve diğer topluluk isteklerine dayanarak). Uzun vadede, farklı türden kullanıcılar için hazırlanmış tatmin edici belgeler hazırlamak isterim. Bunun yanı sıra, bu eğiticilerin hem dilsel hem de yapısal olarak daha tutarlı olmasını sağlamaya çalışacağım. Son olarak, topluluğun mevcut ihtiyaçlarına göre yeni eğitici içerikler yazmayı da amaçlıyorum.
Kullanıcı anketi:
Kullanıcı anketiyle ilgili olarak, Google Formlar'ı çeşitli nedenlerle kullanmayı öneriyorum. Öncelikle, Google Formlar ücretsizdir ve sınırsız işlevsellik (katılımcı sayısı, soru vb. açısından) sunar, cazip bir görsel forma, en kullanışlı anket seçeneklerine (örneğin, özelleştirilmiş doğrusal ölçek, onay kutuları ve çoktan seçmeli) sahiptir ve en önemlisi, sonuçlar istatistiksel analiz amacıyla kolayca dışa aktarılabilir. İnternette yapılan araştırmalara göre Google Formlar'ın anket yapmak için en azından şimdilik en iyi ücretsiz araç olduğu anlaşılıyor. Daha önemsiz bir nokta olarak, Google tarafından yürütülen bir girişimde Google ürününü kullanmak iyi bir jest olur.
Örnek sorular içeren bir ön anket oluşturdum (https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform adresinden erişilebilir). Son versiyonda makul sayıda soru on ila on beş arasında olmalıdır. Somut sonuçlar elde etmek için, çoğunlukla çoktan seçmeli sorular, doğrusal bir ölçek ve birkaç onay kutusu kullanmanızı öneririz. Ancak, doğrusal ölçek tüm spektruma benzememelidir (yalnızca karışıklığa neden olur ve sonuçlar, yüksek dağılım gösterebilir). En fazla iki açık uçlu soru sorulmalıdır, aksi takdirde sonuçlar son derece dağınık olacaktır ve hiç faydalı olmayacaktır. Veriler istatistiksel yazılımlarla kolayca dışa aktarılabildiği ve otomatik olarak analiz edilebildiği için, çok sayıda yanıtın bile sorun yaratacağını düşünüyorum. Yanıt sayısının gerçekten çok yüksek olduğunu varsayarsak, açık uçlu soruların analizi biraz zaman alabilir, ancak bunaltıcı olmayacağını varsayıyorum. Sonuçta ortalama bir kullanıcının belgelerin durumu hakkında kompozisyon yazması pek olası değildir. En kötü senaryoda bazı yanıtlar gelecekteki analizler için saklanabilir.
Grafik kılavuzlar:
Grafik kılavuzlar (gezinme aracı olarak amaçlanan) konusundaki vizyonum, insanların (çoğu) sadece metin temelli bilgileri değil, basit görsel yapıları daha iyi işleme konusunda popüler olduğu gerçeğini temel alıyor. Dahası, benzer ilgi alanlarını birbirine bağlayan çizgiler içeren tematik odaklı bir diyagram şüphesiz daha az deneyimli kullanıcılar için (ve yalnızca değil) oldukça değerli bir varlıktır.
Uygulama ayrıntıları konusunda TikZ paketini kullanmayı öneririm. Her şeyden önce, bu güçlü bir araçtır ve yakında kullanımdan kaldırılma riski söz konusu değildir. Aynı zamanda yüksek kaliteli çıktılar sunar, gerçekten sağlam belgeler içerir ve TeX StackExchange ve diğer ana akım forumlarda sık sorulan bir konudur. En önemlisi, TikZ dosyasının (daha kesin belirtmek gerekirse, içindeki çok sayıda köprünün) HTML belgeleriyle entegrasyonu, TikZ resminin HTML'ye yerleştirilmesine yönelik çeşitli paketlerin ve düzeltmelerin bulunması (örneğin, TeX4ht) nedeniyle önemli bir sorun oluşturmamaktadır.
SciPy içinde kılavuzların gelecekte bakımıyla ilgili sorun, örneğin Overleaf (ortak çalışmayı kolaylaştırır ve anında önizleme sunar) ve sağlayacağım önceden tanımlanmış şablonlar kullanılarak kolayca çözülebilir. Temel olarak, grafik kılavuzların birbirinden büyük bir fark yaratması pek olası değildir. Yapı, renk paleti ve şekiller aşağı yukarı değişkenlik göstereceğinden, daha sonra yeniden şekillendirme ve daha fazla özelleştirme sorun teşkil etmeyecektir.
(Lütfen teklifin tam sürümüne bakın. Paylaşılan GSoD klasöründe bulabilirsiniz.)