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:
- Creative Commons
- Teknik yazar:
- nimishnb
- Proje adı:
- Kelime Kullanımı Kılavuzu
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Proje Özeti
Vocabulary, web sitesi oluşturmak için birincil kullanıcı arayüzü bileşen kitaplığı olarak kullanılabilecek muazzam bir potansiyele sahiptir. Gerekenler sağlam ama basit bir "Nasıl Yapılır?" kılavuzudur. Bileşen kılavuzları, kullanım özellikleri ve yapılandırma düzenlemeleri gibi önemli geliştirici bilgileri, tüm dokümanların önemli bir bölümünü oluşturur. Bu sayede, mevcut kullanıcılar Vocabulary'nin nasıl büyüdüğünü ve yeni hedeflere ulaştığını öğrenebilir. Ayrıca, Vocabulary'nin nispeten daha yeni projelerde kullanımını teşvik edebilirsiniz. Stajyer olarak yaptığım çalışmanın istenilen sonuçları arasında, önceden var olan bileşenlerin kullanımıyla ilgili basit bir kılavuz yazmanın yanı sıra Vocabulary, Vue-Vocabulary ve Fonts için bir ana sayfa tasarlayıp geliştirmek (her biri için entegre bir dokümana yol açar) de yer alıyor.
Proje Planı
Sorun: Belgeler, belirli bir açık kaynak kitaplığının ne kadar başarılı olacağını belirleyen başlıca nedenlerden biridir. Geliştiricilerin uygulamalarını oluşturmak için uygun bir teknoloji yığını seçerken düşündükleri başlıca soru şudur: "Kitaplık iyi belgelendi mi? İyi korunuyor mu? Önemli bir kullanım ve hata desteği sunuyor muyum?". Bu proje fikrini ele alırken kendimize tam olarak bu soruları sormalıyız. Yazılım mühendisliği açısından:
Gereksinim Analizi: İhtiyaçlarımız için kısa ve birleştirilmiş bir dokümana sahip olmamız gerekiyor. Belge eksikliği, açık kaynak uygulamaların gelecekteki görünümünü olumsuz etkiler ve kesinlikle önemli ve göz ardı edilemez bir bileşendir. Bu dokümanlara bağlantı vererek kullanıcıların ilgisini anında çekecek ilgi çekici bir ana sayfa oluşturabilirsiniz. Belgelerin sorunsuz şekilde yürütülebilmesi için belgelerin iyi düzenlenmiş olması gerekir.
Spesifikasyonlar: Gereksinimlere bağlı olarak teknik özellikler belirlenebilir. Dokümanlar, CC netlify web sitelerindeki verilerden ve semantic-ui, scikit-learn, numpy, bootstrap gibi tanınmış dokümanlardan esinlenerek oluşturulabilir. Bu görevin çıktısı, gerekli açılış sayfası ve eksiksiz doküman kılavuzları olacaktır.
Şu anda Vocabulary, Vue-Vocabulary ve Yazı Tipleri ile ilgili bazı genel sorunlar:
Herhangi bir belge eksikliği vardır ve bir kısmı olsa bile, belgenin bir kısmı net web sitelerinde dağılmış durumdadır. Bu, kullanıcıların, geliştiricilerin veya harici katkıda bulunanların kitaplığımızı kullanmasına olanak tanımaz.
Belirli bir bileşene gidip ilgili kodu kopyalamak için ek tıklamalar gerekir. "Tabs component CC Vocabulary" (Sekmeler bileşeni CC Vocabulary) gibi bir terim için yapılan basit bir Google araması, istenen bilgileri döndürmez. Belge kılavuzlarında bir arama seçeneği kullanıcı deneyimini büyük ölçüde iyileştirecektir.
Bileşenler için, anlaşılır olmayan ayrıntıları açıklayan, metin açısından biraz daha ayrıntılı bir açıklama.
Canlı yayınlama seçeneği yoktur. Canlı çalıştırma, geliştiricilerin çalıştığını görmek için uygulamanın tamamını çalıştırmadan bileşeni tanımak üzere JSFiddle gibi çeşitli siteler tarafından desteklenir.
Çözüm
Olası birçok çözüm vardır. Ancak burada birkaçına değineceğim ve nihai çözümümü sonuç bölümünde sunacağım:-
= readthedocs'u kullanma readthedocs, açık kaynak kitaplıklar için doküman yazmak üzere kullanılan iyi bilinen bir çözümdür. Python doküman aracı Sphinx'i temel alır.
Artıları:
- Ethereum (Solidity) gibi kuruluşlar tarafından kullanılan, yaygın olarak kabul gören bir doküman oluşturma biçimidir.
- Optimum şekilde yapılandırılmış dokümanlar.
- Ücretsiz statik barındırma.
Eksileri:
- Stil üzerinde tam kontrol sahibi değilsiniz.
= Sphinx kullanma Dokümanlar bölümü için de Sphinx'i doğal olarak kullanabiliriz. Tüm amaçlarımız için iyi özellikler sunar.
Artıları:
- Dokümanlar için en popüler Python aracı.
- Belge aramaları için de destek vardır.
- Varsayılan CSS, özel bir CSS ile geçersiz kılınabilir; .rst dosyaları kullanılarak HTML üzerinde bazı kontroller yapılabilir.
Eksileri:
- Python ve yeniden yapılandırılmış metin biçimi (.rst) ile kodlamayı içerebilir. Bu da önerilen proje dillerinden sapma oluşturur.
= Jekyll Temalarını Kullanma Jekyll temaları github sayfalarına entegre edilmiştir ve ihtiyaçlarımıza göre özelleştirilebilen mevcut şablonlar mevcuttur.
Artıları:
- Her amaç için hazır doküman temaları.
- Varsayılan CSS ve stiller özel olanlarla geçersiz kılınabilir. HTML üzerinde de kontrol sahibi olabilirsiniz.
- Sayfaları oluşturmak için varsayılan Primer CSS'yi alır.
- GitHub sayfalarıyla kolay entegrasyon.
Eksileri:
- En iyi belge yapısını sunmayabilir.
=GitHub sayfalarını kullanma Statik sitemizi (HTML, CSS, JS) oluşturmak için kullanılan standart github sayfaları.
Artıları:
- Söz konusu olan neredeyse her şey üzerinde tam kontrol.
- Düzen, renkler ve stillere karar verme konusunda maksimum esneklik.
- Kelime bilgisi bileşenlerinin kolay kullanımı.
- Kod snippet'lerinin ve canlı çalıştırma bağlantılarının kolayca yerleştirilmesi.
Eksileri:
- Daha zaman alıcı bir yaklaşım olabilir.
= Haroopad'i kullanma Bunun yerine alternatif bir markdown çözümü sunulur.
Artıları:
- Minimum kodlama gerektirir.
- Odak noktası, dokümanları mükemmel bir şekilde yazmak olacaktır.
Eksileri:
- CSS üzerinde kontrol eksikliği.
- En iyi topluluk desteğine sahip olmayabilir.
- MDX desteklemeyebilir.
= MKDocs'u kullanma Bunun yerine başka bir alternatif markdown çözümü sunulur.
Artıları:
- Bu işlem, minimum düzeyde karmaşık kodlama gerektirir (yine).
- Daha fazla yazın, daha az kod yazın yaklaşımı.
Eksileri:
- CSS üzerinde kontrol eksikliği.
- En iyi topluluk desteğini sağlamıyor olabilir.
- Python kullanılır. Ayrıca bir Amazon S3 örneği oluşturmanız gerekebilir.
= VueJS +StorybookJS kullanma Bu yaklaşım, Vocabulary ve kardeş depolarında yaygın olarak kullanılır.
Artıları:
- Geçmiş iş deneyimleri göz önüne alındığında, iyi çalışacağı garanti edilen teknolojilere bağlı kalmak.
- Kod tabanı hakkında bilgi
- Bu alanda yeterli teknoloji yok.
Eksileri:
- Aynı amaçlar için daha basit seçenekler de kullanılabilir.
Sonuç olarak, VueJS+Storybook yaklaşımını (HTML,CSS,JS) içeren yaklaşımın, kendimi daha rahat hissettiğim için en uygun seçenek olduğunu düşünüyorum. Yine de bu durum, bu uygulamayı geliştirme sürecimizden tamamen uzaklaşmayacağımız anlamına da geliyor. Ayrıca, CC-Kelime Bilgisi bileşenlerini kullanmak da oldukça kolaydır. Ancak dokümanların yapısına karar vermek için readthedocs dokümanlarında içeriğin alt başlıklar arasında nasıl bölündüğünü kesinlikle dikkate almamız gerekir. Minimalist bir görünüme sahip olduğu ve kullanıcıların istediklerini birkaç tıklamayla kolayca bulabileceği için StoryBook kullanan Semantic-UI web sitesi beni etkiledi. Semantik kullanıcı arayüzünün yanı sıra, çalışmalarımda kullanıcı arayüzü stil kılavuzları ve tasarım sistemleri olarak kullanılacak Materyal Tasarım, Primer, Bootstrap, Carbon Design gibi araçlardan da yararlandım. Buna ek olarak, ilham almak için hazır Jekyll belgesi temalarına da bakabiliriz.