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:
- Creative Commons
- Teknik yazar:
- nimishnb
- Projenin adı:
- Kelime Sözlüğü Kullanım Kılavuzu
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Proje Özeti
Sözlük, web sitesi oluşturmak için birincil kullanıcı arayüzü bileşeni kitaplığı olarak kullanılma konusunda muazzam bir potansiyele sahiptir. Bunun için hem sağlam hem de uzman olmayanlara uygun bir "Nasıl Yapılır?" kılavuzu gerekiyor. Bileşen kılavuzları, kullanım spesifikasyonları ve yapılandırma ince ayarları gibi önemli geliştirici bilgileri, tüm belgelerin önemli bir parçasını oluşturur. Bu, hem mevcut kullanıcıları hem kelime dağarcıklarının nasıl geliştiğine ve yeni ara hedeflere nasıl ulaşmaya nasıl devam ettiklerine dair fikir edinmeye teşvik edecek hem de daha yeni projelerde Kelime hazinesinin kullanımını teşvik edecektir. Stajyer olarak benim için arzuladığım sonuçlar, sadece mevcut bileşenlerin kullanımıyla ilgili anlamsız bir kılavuz hazırlamakla kalmayıp Kelime Bilgisi, Kelime Sözlüğü ve Yazı Tipleri için birer ana sayfa tasarlama ve (her biri için entegre bir doküman da sağlar) tasarlamayı da kapsıyor.
Proje Planı
Sorun: Belgeler, belirli bir açık kaynak kitaplığının ne kadar başarılı olacağını belirleyen temel nedenlerden biridir. Geliştiricilerin uygulamalarını oluşturmak için uygun bir teknoloji yığını seçerken düşündükleri en önemli soru "Kitaplık iyi belgelenmiş mi? Bakımlı mı? Ciddi düzeyde kullanım ve hata desteği var mı?” gibi sorular sorabilirsiniz. Bu proje fikrini ele alırken kendimize tam olarak bu soruları sormamız gerekir. Yazılım mühendisliği açısından:
Gereksinim Analizi: İhtiyaçlarımız için mutlaka kısa, öz ve birleştirilmiş bir belgeye ihtiyaç duyuluyor. Belge eksikliği, açık kaynak uygulamalarının gelecekteki perspektiflerini olumsuz yönde etkiler ve bu nedenle göz ardı edilemeyecek önemli bir bileşendir. Bu belgelere verilen bağlantılar, ilgi çekici bir ana sayfa olmalı ve kullanıcıların ilgisini anında çekmelidir. Belgelerin iyi organize edilmiş olması, dolayısıyla sorunsuz bir akış sağlaması gerekir.
Spesifikasyonlar: Gereksinimlere bağlı olarak spesifikasyonlara karar verilebilir. Belgelerdeki içerik, semantic-ui, scikit-learn, numpy, bootstrap vb. gibi tanınmış belgelerden esinlenilerek, CC netlify web sitelerinde bulunan verilerden elde edilebilir. Bu görevin çıktısı, gerekli açılış sayfası ve eksiksiz doküman kılavuzları olacaktır.
Şu anda Kelime Bilgisi, Kelime Bilgisi ve Yazı Tipleri ile bağlantılı bazı genel sorunlar:
Belge eksiktir ve bazı dokümanlar mevcut olsa bile bazı bölümleri netlify web sitelerinde farklı yerlere dağılmış durumdadır. Bu şart, kullanıcıların, geliştiricilerin veya harici katkıda bulunanların kitaplığımızı kullanmasını engellemez.
Belirli bir bileşene ulaşmak ve ilgili kodu kopyalamak için ek tıklamalar gerekir. "Sekme bileşeni CC Kelime Bilgisi" gibi bir Google araması, istenen bilgileri döndürmez. Belge kılavuzlarındaki Arama seçeneği kullanıcı deneyimini büyük ölçüde iyileştirir.
Bileşenler için metin halinde daha ayrıntılı ve açık olmayan ayrıntıları açıklayan bir açıklama.
Canlı çalıştırma seçeneği yoktur. Canlı çalıştırma, JSFiddle gibi çeşitli siteler tarafından desteklenir. Böylece geliştiriciler, bileşenin nasıl çalıştığını görmek için uygulamanın tamamını çalıştırmadan bileşen hakkında fikir sahibi olabilir.
Çözüm
Olası birden çok çözüm vardır. Ancak burada birkaçına değinerek nihai çözümümü sonuç kısmında sunacağım:
= readthedocs readthedocs kullanımı, açık kaynak kitaplıklar için belge yazma konusunda iyi bilinen bir çözümdür. Bu uygulama, python belgeleme aracı olan Sfenks'i temel alır.
Artıları:
- Ethereum (Solidity) gibi kuruluşlar tarafından kullanılan, yaygın olarak kabul edilen belge oluşturma biçimi.
- En uygun şekilde yapılandırılmış dokümanlar.
- Ücretsiz statik barındırma.
Eksileri:
- Stil üzerinde mutlak kontrol eksikliği.
= Sfenks'i Kullanma Sfenks'i belgelendirme kısmında da kullanabiliriz. Sfenks tüm amaçlarımız için faydalı özellikler sunar.
Artıları:
- Belgeleme 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. Bazı öğeler .rst dosyaları kullanılarak HTML üzerinde kontrol edilebilir.
Eksileri:
- Python ve yeniden yapılandırılmış metin biçiminde (.rst) kodlamayı gerektirenler, önerilen proje dillerinden sapmaya neden olur.
= Jekyll Temalarını Kullanma Jekyll temaları github sayfalarına entegre edilmiştir ve ihtiyaçlarımıza göre özelleştirilebilen önceden hazırlanmış şablonlar vardır.
Artıları:
- Her türlü amaca uygun, hazır belgeleme temaları.
- Varsayılan CSS ve stiller, özel olanlarla geçersiz kılınabilir, HTML üzerinde de kontrol.
- Sayfaları oluşturmak için varsayılan Primer CSS'yi alır.
- GitHub sayfalarıyla kolay entegrasyon.
Eksileri:
- En iyi belge yapısını sağlamayabilir.
=GitHub sayfalarını kullanma Statik sitemizi (HTML, CSS, JS) oluşturmak için standart gitHub sayfaları kullanılır.
Artıları:
- Söz konusu neredeyse her şey üzerinde tam kontrol.
- Düzeni, renkleri ve stilleri belirlemede maksimum esneklik.
- Sözlük bileşenlerinin kullanımı kolay.
- Kod snippet'lerini ve canlı yayın bağlantılarını kolayca yerleştirme.
Eksileri:
- Daha fazla zaman alan bir yaklaşım olabilir.
= Haroopad kullanmak Bu, bunun yerine alternatif bir Markdown çözümü sağlar.
Artıları:
- Minimum düzeyde karmaşık kodlamalar gerektirir.
- Belgeleri mükemmel bir şekilde yazmaya odaklanılmalıdır.
Eksileri:
- CSS üzerinde kontrol eksikliği.
- En iyi topluluk desteğine sahip olabilir veya olmayabilir.
- MDX desteklenmiyor olabilir.
= MKDokümanlar'ı kullanmak Bu, bunun yerine alternatif bir Markdown çözümü sunar.
Artıları:
- Minimum düzeyde karmaşık kodlama gerektirir (yine).
- Daha fazla yazın, daha az kod yazın.
Eksileri:
- CSS üzerinde kontrol eksikliği.
- En iyi topluluk desteğine sahip olmayabilir.
- Python kullanır. Daha fazla bir Amazon S3 örneği çalıştırmak gerekebilir.
= VueJS +StorybookJS Kullanma Bu yaklaşım, Vocabulary ve kardeş depolarında yaygın olarak kullanılmaktadır.
Artıları:
- Geçmiş iş deneyimleri göz önünde bulundurulduğunda, sorunsuz çalışacağı garanti edilen teknolojilere bağlı kalın.
- Kod tabanına aşina olma.
- Bu alanda yetkin bir teknoloji yok.
Eksileri:
- Aynı amaç için daha basit seçenekler de sunulabilir.
Sonuç olarak VueJS+Storybook yaklaşımını (HTML,CSS,JS) içeren yaklaşımın benim için en uygun seçenek olduğunu düşünüyorum. Ancak bu, söz konusu uygulamayı geliştirirken kendimize de bir şey yapmayacağımız anlamına geliyor. CC-kelimesi bileşenlerini kullanmak da oldukça kolay olurdu. Bununla birlikte, dokümanların yapısına karar verirken, readthedocs dokümanlarında içeriğin alt başlıklar arasında nasıl bölündüğünü kesinlikle değerlendirmemiz gerekir. Minimalist bir görünüme sahip olması ve kullanıcıların sadece birkaç tıklamayla istediklerini kolayca anlayabilmeleri açısından (StoryBook kullanan) Semantic-UI web sitesinden çok etkilendim. Semantik kullanıcı arayüzünün dışında, işim için kullanıcı arayüzü stil kılavuzu ve tasarım sistemleri olarak kullanılacak Materyal Tasarım, Primer, Bootstrap, Karbon Tasarım vb. konulara da göz attım. Bunun için ilham almak amacıyla hazır Jekyll doküman temalarına da bakabiliriz.