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:
- SciPy
- Teknik yazar:
- mkg33
- Proje adı:
- Kullanıcı odaklı dokümanlar ve kapsamlı yeniden yapılandırma
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
Motivasyon:
Farklı ihtiyaçları olan kullanıcıların kolayca erişebilmesi için mevcut dokümanları yeniden düzenleme konusunda çalışmayı planlıyorum. Bir araştırmacının büyük olasılıkla gelişmiş ve ince ayrıntılara sahip özelliklerle ilgilendiği, daha önce uzmanlığı olmayan bir kullanıcının ise adım adım açıklamalı kılavuzlardan ve diyagramlardan yararlandığı açıktır.
Bu projeyi kişisel ve profesyonel nedenlerle sürdürmek istiyorum: Öncelikle, kendi araştırmalarımdan büyük fayda gördüğüm için SciPy'ye önemli ölçüde katkıda bulunmak istiyorum. İkinci olarak, diğer yazılımlarda çok sık yetersiz (veya eksik) dokümanlar görüyorum ve kapsamlı bir kılavuz sağlanmış olsaydı kullanıcıların kodu kullanmayı ne kadar daha hızlı (veya hiç) öğrenebileceğini hep merak ediyorum.
Hedefler:
Mevcut SciPy dokümanlarını 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ımı ve analizi. Başka bir deyişle, çeşitli kullanıcıların dokümanlarla ilgili gereksinimlerini dile getirmelerini sağlayan, internette yürütülen kısa ve öz bir anket. Onların görüşlerinin ilham kaynağı olması gerektiğine inanıyorum (daha kullanıcı dostu dokümanlar nasıl oluşturabiliriz?).
Projenin hayata geçirilmesiyle ilgili olarak, ilk aşamada kullanıcı anketini tasarlayıp analiz etmenin yanı sıra mevcut dokümantasyonda fark ettiğim çeşitli üslup sorunlarını ele alacağız. Örneğin, tutarlılık eksikliği (örnek: iki boyutlu dizilerin yanında yer alan 2 boyutlu diziler), yeniden yazılması gereken karmaşık cümleler veya belirli alt sayfalarda alfabetik sıralamanın olmaması. İkinci aşamada, anket sonuçlarına ve diğer topluluk isteklerine göre alakalı konulara ait köprü bağlantıları içeren grafik kılavuzları kullanıma sunulacaktır. Uzun vadede, farklı kullanıcı türlerine göre uyarlanmış tatmin edici bir dokümana ulaşmayı amaçlıyorum. Ayrıca, eğiticileri hem dil bilgisi hem de yapısal olarak daha tutarlı hale getirmeye çalışacağım. Son olarak, mevcut topluluk ihtiyaçlarına göre yeni eğitimler yazmaya devam etmeyi planlıyorum.
Kullanıcı anketi:
Kullanıcı anketi için birkaç nedenden dolayı Google Formlar'ı kullanmanızı öneririm. Öncelikle Google Formlar ücretsizdir ve sınırsız işlevsellik sunar (ör. katılımcı sayısı, soru sayısı vb.). Ayrıca, ilgi çekici bir görsel forma, en kullanışlı anket seçeneklerine (ör. özelleştirilebilir doğrusal ölçek, onay kutuları ve çoklu seçim) sahiptir ve en önemlisi, sonuçları istatistiksel analiz amacıyla kolayca dışa aktarabilirsiniz. İnternetteki araştırmalara göre, en azından şimdilik anket yapmak için en iyi ücretsiz araç Google Formlar. Daha ciddi olmasa da Google tarafından yürütülen bir girişimde bir Google ürününü kullanmak uygun bir jest olabilir.
Örnek sorular içeren bir ön anket oluşturdum (https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform adresinden ulaşabilirsiniz). Nihai sürümde on ila on beş soru olması uygundur. Somut sonuçlar elde etmek için çoğunlukla çoktan seçmeli sorular, doğrusal ölçek ve birkaç onay kutusu kullanılmasını öneririm. Ancak doğrusal ölçek tam bir spektruma benzememelidir (bu durum yalnızca kafa karışıklığına neden olur ve sonuçların yüksek dağılım gösterme olasılığı yüksektir). En fazla iki açık uçlu soru olmalıdır. Aksi takdirde, sonuçlar büyük ölçüde dağılmış olur ve hiç faydalı olmaz. Çok fazla sayıda yanıtın bile, verilerin kolayca dışa aktarılıp istatistiksel yazılımla otomatik olarak analiz edilebileceği için sorun olmayacağı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 çok fazla zaman almayacağını düşünüyorum. Sonuçta, ortalama bir kullanıcının belgelerin durumuyla ilgili bir makale yazması pek olası değildir. En kötü senaryoda, bazı yanıtlar gelecekteki analizler için depolanabilir.
Grafik kılavuzlar:
Grafik kılavuzlarla (gezinme aracı olarak kullanılması amaçlanmıştır) ilgili vizyonum, insanların (çoğu) tamamen metne dayalı bilgilerden ziyade basit görsel yapıları işlemede daha iyi olduğu yaygın bir varsayıma dayanır. Ayrıca, benzer ilgi alanlarını birbirine bağlayan çizgilerin yer aldığı tematik bir şema, daha az deneyimli kullanıcılar için (ve sadece onlar için değil) şüphesiz son derece değerli bir öğedir.
Uygulama ayrıntıları için TikZ paketini kullanmanızı öneririm. Öncelikle, bu güçlü bir araçtır ve yakında desteğinin sonlandırılma riski yoktur. Aynı zamanda yüksek kaliteli çıktılar sağlıyor, gerçekten sağlam dokümanlar içeriyor ve TeX StackExchange ve diğer yaygın forumlarda sıkça kullandığım bir konu. En önemlisi, bir TikZ dosyasının (daha doğrusu, içindeki çok sayıda köprü bağlantısının) HTML dokümanlarıyla entegrasyonu, TikZ resmini HTML'ye yerleştirmeye yönelik çeşitli paketler ve düzeltmeler (ör. TeX4ht) bulunduğundan önemli sorunlara neden olmuyor.
SciPy'deki kılavuzların gelecekte bakımı, 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 çok farklı olması olası değildir. Yapı, renk paleti ve şekiller aşağı yukarı aynı kalacağı için daha sonra yeniden şekillendirme ve daha fazla özelleştirme yapmak sorun olmayacaktır.
(Lütfen paylaşılan GSoD klasöründeki teklifin tam sürümüne bakın.)