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:
- Ulusal Ağ Biyolojisi Kaynağı (NRNB)
- Teknik yazar:
- Prubhtej_9
- Proje adı:
- SynBioHub için kullanıcı dokümanları oluşturma ve belirli kullanım alanları için eğitici içerikler geliştirme
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Soyut
Kullanıcı dokümanları, son kullanıcıların bir ürünü veya hizmeti kullanmasına yardımcı olmak için tasarlanmıştır. İyi kullanıcı dokümantasyonu çok önemlidir; kullanıcılara bir yazılımın nasıl kullanılacağını, yazılımın özelliklerini, ipuçlarını, püf noktalarını ve yazılımı kullanırken karşılaşılan yaygın sorunları çözmeyi öğrenmeleri için bir yol sağlar. Ayrıca destek maliyetini azaltır ve ürünün kurumsal kimliğinin bir parçasıdır. Yani iyi bir kullanıcı dokümanı, sağlıklı bir ürünün ve geliştirici ekibinin göstergesidir. İyi bir kullanıcı dokümanları olmadan kullanıcılar yukarıda bahsedilen işlemleri etkili ve verimli bir şekilde nasıl yapacaklarını bilemez. Mükemmel iletişim, tüm işletmelerin veya ürünlerin merkezinde yer alır ve her zaman önemlidir. İyi bir belgeleme bu iletişimi her zaman için alır ve herkesin başarıya ulaşmak için erişebileceği, yönetilebilir bir çerçeveye koyar. SynBioHub, sentetik biyoloji için bir tasarım deposudur. Hem herkese açık bir web sitesi hem de açık kaynak yazılım olarak kullanılabilir. SynBioHub, genetik tasarımları temsil etmek için açık kaynak bir standart olan Sentetik Biyoloji Açık Dili'ni (SBOL) kullanır ve GenBank ile FASTA dosyalarındaki tasarım parçalarının paylaşılmasına da olanak tanır. SynBioHub, sentetik parça ve tasarım kitaplığını hizmet olarak yayınlamak, tasarımları ortak çalışanlarla paylaşmak ve biyolojik sistemlerin tasarımlarını yerel olarak depolamak için kullanılabilir. SynBioHub'daki verilere HTTP API, Java API veya Python API aracılığıyla erişilebilir. Bu veriler daha sonra genetik tasarımlar oluşturmak için CAD araçlarına entegre edilebilir. SynBioHub, kullanıcıların veritabanına yeni biyolojik veriler yüklemesi, DNA parçalarını görselleştirmesi, istenen parçalara erişmek için sorgu yapması ve SBOL, GenBank, FASTA vb. indirmesi için bir arayüz içerir. Ayrıca internette aşağıdakiler gibi çeşitli araştırma makaleleri ve bazı eğitici kaynaklar da mevcuttur: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub'da yalnızca API ile ilgili bazı dokümanlar mevcuttur. GUI için doküman yoktur.
Dokümanların mevcut durumu:
Şu anda kullanıcı dokümanları "https://synbiohub.github.io/api-docs/#about-synbiohub" adresinde mevcuttur. Bu yalnızca API dokümanlarıdır ve kullanıcının tasarım deposunda gezinmesine yardımcı olabilecek kullanıcı arayüzü dokümanı yoktur. Ayrıca, API dokümanlarında da biraz güncelleme yapılması gerekiyor. Kullanıcının karşılaşabileceği belirli sorunların giderilmesi gibi belirli konuları da hesaba katın. Kuruluş, buradaki gibi bazı eğitim videoları kaydetmiş. SynBioHub ile ilgili kullanıcıya yol gösterebilecek yazılı bir kullanıcı dokümanı yok.
Önerdiğiniz kullanıcı dokümanları neden mevcut dokümanlara göre daha iyi? GUI dokümanlarını, danışmanımız Bay Chris Myers'ın önerdiği gibi GitHub ve markdown kullanarak sıfırdan oluşturacağım. Önerilen kullanıcı dokümanları, tüm son kullanıcılar için verimliliği, tutarlılığı ve gönül rahatlığını iyileştirmek ve sağlamak üzere yapılandırılacak. Yazılı kılavuzları ve ilişkili resimleri içeren bu dokümanda, açık kaynak simülasyon aracı SynBioHub'ın her özelliğinin nasıl kullanılacağına dair talimatlar ve açıklamalar yer alır. Bay Myers ile yaptığımız görüşmelerde , API dokümanının GUI ile birleştirilmesine ve 6 bölümden oluşmasına (bunlardan 6. bölüm isteğe bağlı olacak) karar verildi. Bölümlerden aşağıdaki şekilde bahsedilmektedir: 1. Giriş 2. Yükleme talimatları a) Önceden oluşturulmuş görüntüden b) Kaynaktan c) NGINX yapılandırması 3. Kullanıcı Talimatları a) Her bir GUI özelliğinin nasıl kullanılacağıyla ilgili ayrıntılı talimatlar b) Yaygın kullanım alanlarına yönelik eğitici içerikler 4. API Belgeleri - Uç noktalar bölümü 5. Eklenti Dokümanları 6. Sorun giderme ve gelecekte referans olarak kullanabileceğiniz bilgiler.
Bölüm 1:
Bu bölümde, kullanıcılara SynBioHub ile ilgili ayrıntılı bir giriş ve çeşitli eğitici içerikler sunulur.
2. Bölüm:
Bu bölümde, kullanıcının açık kaynak yazılımı çeşitli yöntemler kullanarak yükleyebileceği çeşitli yöntemler açıklanmaktadır. Bu yöntemler şunlardır: a) Önceden oluşturulmuş görüntüden b) Kaynaktan c) NGINX yapılandırması
Bölüm 3:
Bu, belgelerin en önemli kısmıdır ve çoğu zaman alacaktır. Burada, her dakika ayrıntısı GUI'ye bağlam içinde eklenecektir. Yukarıda da belirtildiği gibi, bu bölümde temel olarak iki konu ele alınacaktır: her GUI özelliğinin nasıl kullanılacağına dair ayrıntılı talimatlar ve yaygın kullanım alanlarına yönelik bazı eğitici içerikler.
Bölüm 4:
Yukarıda belirtildiği gibi, bu bölümün dokümanlarını oluşturmak için slate kullanılır. Bu bölüme aşağıdaki uç noktalar dahil edilir: 1. Kullanıcı Uç Noktaları 2. Uç noktaları ara 3. Endpoints'i indirin 4. Uç noktaları indirin 5. Gönderim Uç Noktaları 6. İzin uç noktaları. 7. Uç noktaları düzenleme 8. Ek Uç Noktaları 9. Yönetim uç noktaları
Bölüm 5:
Bu bölüme, eski SynBioHub dokümanlarında bulunan eklenti dokümanları eklenecektir. Bu bölüm, eklenti spesifikasyonu ve uygulama olmak üzere iki alt bölüme ayrılır. Bölüm 6: [İsteğe bağlı] Bu bölümde, kullanıcıların karşılaştığı yaygın hataların listesi ve bazı sorun giderme talimatları yer alır. Bay Myers ile yaptığımız görüşmeye göre, çok uzun olmaması koşuluyla bu bölümün giriş bölümüyle birleştirilmesine karar verildi. Analiz Bay Myers ile mevcut dokümanların nasıl güncelleneceği ve GUI için yeni bir doküman nasıl yazılacağı hakkında konuştuk. Bu birkaç görüşmede, yukarıda bahsedilen yeni dokümanlar için temel bir düzen oluşturduk. Aşağıdaki 5. sayfada, tahmini zaman çizelgesi verilmiştir. Görüşmemize göre, dokümanın 4. Bölümü hariç her bölümün dokümanlarını oluşturmak için github ve markdown kullanacağım. Slate: Slate, güzel, akıllı ve duyarlı API belgeleri oluşturmanıza yardımcı olur. Slate, bir dizi Markdown dosyasından harika görünümlü, üç panelli bir API dokümanı statik sitesi oluşturan Ruby tabanlı bir araçtır. Proje yöneticisi Robert Lord tarafından 2013'te seyahat yazılımları şirketi "Tripit"te 18 yaşında stajyerken geliştirildi. O zaman patronunu projeyi açık kaynaklı hale getirmesine izin vermeye ikna etti. Gerisi tarih. Aşağıdaki özelliklere sahiptir: • Net, sezgisel tasarım: Slate'te API'nizin açıklaması dokümanınızın sol tarafında, tüm kod örnekleri ise sağ tarafta yer alır. Stripe ve PayPal'ın API dokümanlarından esinlenmiştir. Slate duyarlı olduğundan tabletlerde, telefonlarda ve hatta basılı olarak harika görünür. • Her şey tek bir sayfada: Kullanıcılarınızın istediklerini bulmak için milyonlarca sayfayı taraması gereken günler geride kaldı. Seçenek listesi, tüm dokümanları tek bir sayfaya yerleştirir. Ancak bağlantı oluşturma özelliğinden ödün vermedik. Ekranı kaydırırken tarayıcınızın karması en yakın başlığa göre güncellenir. Bu sayede dokümanda belirli bir noktaya bağlantı oluşturmak doğal ve kolaydır. • Slate, Markdown'dan ibarettir: Slate ile doküman yazarken yalnızca Markdown yazarsınız. Bu sayede dokümanları kolayca düzenleyebilir ve anlayabilirsiniz. Her şey Markdown'da yazılmıştır. Kod örnekleri bile yalnızca Markdown kod bloklarıdır. • Birden fazla dilde kod örnekleri yazın: API'niz birden fazla programlama dilinde bağlandıysa bunlar arasında geçiş yapmak için sekmeler ekleyebilirsiniz. Belgenizde, GitHub Flavored Markdown'da olduğu gibi her kod bloğunun üst kısmında dil adını belirterek farklı dilleri ayırt edersiniz. • 100'den fazla dil için hazır söz dizimi vurgulama özelliği, yapılandırma gerekmez. • Sayfanın en sol tarafında bulunan içindekiler bölümü otomatik, sorunsuzca kaydırılır. Ekranı kaydırırken dokümanda bulunduğunuz yeri gösterir. Ayrıca hızlıdır. TripIt'te, yeni API'miz için doküman oluşturmak amacıyla Slate'i kullanıyoruz. İçerik dizinimizde 180'den fazla giriş bulunuyor. Büyük boyutlu dokümanlar için bile performansın mükemmel kalmasını sağladık. • Kullanıcılarınızın dokümanlarınızı sizin yerinize güncellemesini sağlayın. Varsayılan olarak, Slate tarafından oluşturulan dokümanlarınız herkese açık bir GitHub deposunda barındırılır. Bu, GitHub Pages ile dokümanlar için ücretsiz barındırma hizmeti almanın yanı sıra diğer geliştiricilerin yazım hataları veya başka sorunlar bulursa dokümanlarınıza çekme isteği göndermesini kolaylaştırır. Elbette GitHub'ı kullanmak istemiyorsanız dokümanlarınızı başka bir yerde barındırabilirsiniz. • Sağdan sola düzeni; Arapça, Farsça (Farsi), İbranice gibi RTL dilleri için tam sağdan sola sayfa düzeni kullanır. Verdict Slate, doküman oluşturmak için kullanılan en güçlü açık kaynak yazılımlardan biridir. Mentorum Chris Myers ile yaptığımız görüşmelere göre 4. Bölüm için seçenek listesi, diğer kısımlarda ise github ve markdown kullanacağım. Dokümanların daha ayrıntılı bir görünümü aşağıdaki bölümlerde ele alınmıştır. Önerilen belgelerin yapısı. SynBioHub Kullanıcı Rehberi için bir yapı oluşturdum; bu yapı 2. sayfada bulunabilir. Bu yapı kabul edildi ve Bay Myers tarafından değiştirildi. Proje Hedefleri 1. Belgeleri yeniden yapılandırın. 2. Dokümanları SynBioHub'ın modern sürümlerine uygun olacak şekilde güncelleyin. 3. Güncelliğini yitirmiş bilgileri kaldırın. 4. Kullanıcı dokümanlarını daha anlaşılır hale getirmek için yeniden yazın. 5. Yeni katkıda bulunanların temel biyolojik kavramlar ve SynBioHub arayüzü hakkındaki temel bilgilerini artırmak için dokümanlara kısa bir ön koşul bölümü ekleyin.