Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- SciPy
- Teknik yazar:
- mkg33
- Projenin 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 tarafından kolayca erişilebilir hale getirmek için yeniden düzenlemeyi planlıyorum. Bir araştırmacı büyük olasılıkla gelişmiş ve zorlayıcı özelliklerle ilgilenirken, uzmanlık düzeyi olmayan bir kullanıcının ise adım adım açıklamalı kılavuzları ve diyagramları takdir ettiğini söylemeye gerek yok.
Bu projeye kişisel ve profesyonel nedenlerle devam etmek istiyorum: Öncelikle SciPy'ye önemli ölçüde katkıda bulunmak isterim, çünkü kendi araştırmam bu programdan çok faydalandı ve ikincisi, diğer yazılımlarda sık sık yetersiz (veya eksik) belge buluyorum ve kullanıcılara kapsamlı bir kılavuz sağlanmış olsa bile kullanıcıların kodu nasıl kullanacaklarını 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. Diğer bir deyişle, çeşitli kullanıcıların belgelerle ilgili ihtiyaçlarını dile getirmelerini sağlayan, çevrimiçi olarak yürütülen kısa ve öz bir ankettir. Düşüncelerinin ilham kaynağı olması gerektiğine inanıyorum (daha kullanıcı dostu bir belgeyi başka nasıl oluşturabiliriz?).
Projenin gerçekleştirilmesine gelince, ilk aşamada, kullanıcı anketinin tasarlanması ve analiz edilmesi ve ayrıca mevcut belgede dikkat çeken biçimsel bazı sorunların ele alınması yer alacak. Tutarlılık eksikliği (örnek: 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 olmaması. İkinci aşamada, ilgili konulara bağlantı içeren grafik kılavuzların sunulmasına odaklanacağız (anket sonuçlarına ve diğer topluluk isteklerine dayanarak). Uzun vadede, farklı kullanıcı türlerine göre uyarlanmış tatmin edici dokümanlar elde etmek istiyorum. Bunun yanı sıra, eğitimlerin hem dil 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ğiticiler yazmayı 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şlevler sunar (katılımcı sayısı, soru vb. açısından), ilgi çekici bir görsel forma, en kullanışlı anket seçeneklerine (örneğin, kişiye özel 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. İnternet araştırmalarına göre Google Formlar'ın anket yapmak için en azından şimdilik en iyi ücretsiz araç olduğu görülüyor. Daha az ciddi olarak belirtmek gerekirse, Google tarafından işletilen bir girişimde Google ürününü kullanmak hoş bir jest olacaktır.
Örnek sorular içeren bir ön anket oluşturdum (Ankete https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform adresinden erişebilirsiniz. Son sürümde makul sayıda soru on ile on beş arasında olmalıdır. Somut sonuçlar elde edebilmek için, çoğunlukla çoktan seçmeli sorular, bir doğrusal ölçek ve birkaç onay kutusu kullanmamızı öneririm. Bununla birlikte, doğrusal ölçek tüm spektrumlara benzememelidir (bu yalnızca kafa karışıklığına yol açar ve sonuçların yüksek dağılma olasılığına yol açar). En fazla iki açık uçlu soru sorulabilir. 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ılıp otomatik olarak analiz edilebildiği için, çok sayıda yanıtın bile sorun yaratmayacağını düşünüyorum. Cevap sayısının gerçekten çok yüksek olduğunu varsayarsak, açık uçlu sorular üzerinde yapılan analizin biraz zaman alacağını varsayıyorum. Ancak yine de çok zahmetli olmayacağını düşünüyorum. Sonuçta ortalama bir kullanıcının belgelerin durumu hakkında makale yazması pek olası değildir. En kötü senaryoda bazı yanıtlar gelecekteki analizler için saklanabilir.
Grafik kılavuzlar:
Benim görüşüm grafikli kılavuzlar (gezinme araçları olarak hizmet etme amacıyla) ile ilgili vizyonum, insanların çoğunun yalnızca metin temelli bilgiler yerine, düz görsel yapıları daha iyi işlemeye çalıştığı düşüncesine dayanıyor. Dahası, benzer ilgi alanlarını birleştiren çizgilerin yer aldığı tema odaklı bir diyagram, hiç şüphesiz daha az deneyimli kullanıcılar (sadece değil) için son derece değerli bir öğedir.
Uygulama ayrıntılarına gelince TikZ paketini kullanmayı öneriyorum. Her şeyden önce, güçlü bir araçtır ve yakında kullanımdan kaldırılma riski söz konusu değildir. Ayrıca yüksek kaliteli çıktılar sunar, oldukça sağlam belgeler içerir ve TeX StackExchange ile diğer ana akım forumlarda sıkça dile getirilen 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ştirilmesi için çeşitli paketlerin ve düzeltmelerin (örneğin, TeX4ht) bulunması nedeniyle önemli sorunlar oluşturmamaktadır.
SciPy içinde kılavuzların gelecekte ne şekilde bakım yapacağıyla ilgili soru, ö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 çok farklı olması gerekmez. Yapı, renk paleti ve şekiller neredeyse hiç değişmeyecek, dolayısıyla sonradan yeniden şekillendirme ve daha fazla özelleştirme sorun olmayacaktır.
(Teklifin tam sürümünü görebilirsiniz. Paylaşılan GSoD klasöründe mevcuttur.)