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:
- Ağ Biyolojisi Ulusal Kaynak (NRNB)
- Teknik yazar:
- Prubhtej_9
- Projenin adı:
- SynBioHub için kullanıcı belgeleri oluşturma ve belirli kullanım alanları için eğiticiler geliştirme
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Özet
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ı belgeleri, kullanıcılara bir yazılımı, özelliklerini, ipuçlarını ve püf noktalarını öğrenmeleri ve yazılımı kullanırken karşılaşılan yaygın sorunları çözmeleri için bir yol sağladığından çok önemlidir. Ayrıca destek maliyetini azaltır ve ürünün kurumsal kimliğinin bir parçasıdır. Yani iyi bir kullanıcı belgesi, sağlıklı bir ürünün ve geliştirici ekibinin işaretidir. Kullanıcı, iyi bir kullanıcı dokümantasyonu olmadan yukarıda bahsedilen şeyleri nasıl etkili ve verimli bir şekilde yapacağını bilemeyebilir. Kullanıcı belgeleri bir ürünün başarısında çok önemli bir rol oynayabilir. Çünkü başarılı iletişim, her zaman işletme veya ürünün merkezinde yer alır ve böyle devam edecektir. Mükemmel bir belge ise bu iletişimi alıp herkesin başarı için erişebileceği yönetilebilir bir çerçeveye sokar. SynBioHub, sentetik biyolojiye yönelik bir tasarım deposudur. Hem herkese açık web sitesi hem de açık kaynak yazılım olarak kullanılabilir. SynBioHub, genetik tasarımları temsil etmek için açık kaynak standardı olan Sentetik Biyoloji Açık Dil (SBOL) teknolojisini kullanır. Ayrıca GenBank ve FASTA dosyalarından tasarım parçalarının paylaşılmasına izin verir. SynBioHub, sentetik parçalar ve tasarımlar kitaplığını hizmet olarak yayınlamak, iş arkadaşlarıyla tasarım paylaşmak ve biyolojik sistem tasarımlarını yerel olarak depolamak için kullanılabilir. SynBioHub'daki verilere HTTP API, Java API veya Python API üzerinden erişilebilir ve bu veriler daha sonra genetik tasarımlar oluşturmak üzere CAD araçlarına entegre edilebilir. SynBioHub, bazı biyolojik verileri veritabanına yüklemek, DNA parçalarını görselleştirmek, istenen parçalara erişmek üzere sorgu gerçekleştirmek ve SBOL, GenBank, FASTA vb. indirmek için kullanıcılara yeni biyolojik
Dokümanların Şu Anki Durumu:
Kullanıcı belgelerine şu anda :"https://synbiohub.github.io/api-docs/#about-synbiohub" adresinden ulaşabilirsiniz. Bu, yalnızca API dokümanlarıdır ve kullanıcının tasarım deposunda gezinmesine yardımcı olabilecek GUI dokümanları mevcut değildir. Ayrıca API dokümanlarının, kullanıcının karşılaşabileceği belirli sorunların giderilmesi gibi bazı özel konuların yanı sıra güncellenmesi gerekmektedir. Kuruluş, buradakine benzer bazı eğitim videoları kaydetmiştir. SynBioHub hakkında kullanıcıya yol gösterecek yazılı bir kullanıcı dokümanı yoktur.
Teklif ettiğiniz kullanıcı dokümanları neden mevcut dokümana göre daha iyi? GUI dokümanlarını github ve Markdown'ı kullanarak mentorun Bay Chris Myers'ın önerdiği şekilde sıfırdan oluşturacağım. Teklif edilen kullanıcı dokümanları, son kullanıcılar için verimliliği, tutarlılığı ve huzurunu iyileştirecek ve sağlayacak şekilde yapılandırılacaktır. Bu eğitimde, açık kaynak simülatörü SynBioHub'ın her bir özelliğinin nasıl kullanılacağıyla ilgili talimatlar ve açıklamalar yer alacak. Bu rehberde yazılı kılavuzlar ve ilişkili resimler yer alır. Bay Myers ile yaptığımız görüşmeler sırasında , API dokümanlarının GUI ile birleştirilmesine ve 6 bölümün (6. bölümün isteğe bağlı olacağı) içermesine de karar verildi. Bölümlerden şu ş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ğına ilişkin ayrıntılı talimatlar b) Yaygın kullanım alanlarına yönelik eğiticiler 4. API Belgeleri - Uç noktalar bölüm 5. Eklenti Belgeleri 6. Sorun giderme ve gelecekteki referanslar.
1. Bölüm:
Bu bölümde kullanıcılara SynBioHub ile ilgili ayrıntılı bir giriş ve çeşitli eğitimler sunulacaktır.
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 farklı yöntemler, örneğin: a) Önceden oluşturulmuş görüntüden b) Kaynaktan c) NGINX yapılandırması
3. Bölüm:
Bu, belgelemenin en önemli kısmıdır ve çoğu zamanı kaplar. Burada her dakika ayrıntı GUI'ya bağlam içinde eklenir. Yukarıda da bahsedildiği üzere, bu bölümde iki önemli konu ele alınacaktır. Bu bölümde, her bir GUI özelliğinin nasıl kullanılacağına ilişkin ayrıntılı talimatlar ve yaygın kullanım alanlarına yönelik bazı eğiticiler ele alınmaktadır.
4. Bölüm:
Yukarıda belirtildiği gibi, seçenek listesi bu bölümün belgelerini oluşturmak için kullanılır. Bu bölümde aşağıdaki uç noktalar yer alacaktır: 1. Kullanıcı Uç Noktaları 2. Search Endpoints 3. Endpoints'i indirme 4. Endpoints'i indirme 5. Gönderim Uç Noktaları 6. İzin Uç Noktaları. 7. Uç noktaları düzenleme 8. Ek Uç Noktaları 9. Yönetim Uç Noktaları
5. Bölüm:
Bu bölümde, eski SynBioHub dokümanlarında bulunan eklenti dokümanları eklenecektir. Bu bölüm, eklenti özellikleri ve uygulaması olmak üzere iki bölüme ayrılacaktır. 6. Bölüm: [İsteğe bağlı] Bu bölümde, kullanıcıların karşılaştığı hataların çok yaygın bir listesi ve bazı sorun giderme talimatları bulunur. Bay Myers ile yaptığımız görüşmede, bu bölümün fazla uzun sürmemesi halinde giriş bölümüyle birleştirilebileceğine karar verildi. Analiz Mr. Myers ve mevcut dokümanların nasıl güncelleneceği, ayrıca GUI için yeni bir belgenin nasıl yazılacağı üzerine konuştuk . Bu birkaç konuşmada yeni belgeler için yukarıda bahsedilen ve aşağıdaki 5. sayfada tahmini bir zaman çizelgesi sunan temel bir düzen oluşturduk. Görüşmeye istinaden, seçenek listesinin kullanılacağı belgelerin 4. bölümü hariç her bölümde belgeleri 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 grup markdown dosyasından mükemmel görünümlü, üç panelli API belgeleri statik sitesi oluşturan, Ruby tabanlı bir araçtır. Bu proje, geliştirici Robert Lord tarafından 2013'te seyahat yazılımı şirketi "Tripit"te 18 yaşında stajyerken geliştirildi. O zamanlar patronunu projeyi açık kaynaklı hale getirmesine izin vermeye ikna etti. Geri kalan her şey ise tarih oldu. Şu özelliklere sahiptir: • Sade, sezgisel tasarım — Slate'te API'nizin açıklaması belgelerinizin sol tarafında, tüm kod örnekleri ise sağ taraftadır. Stripe ve PayPal'ın API belgelerinden esinlenilmiştir. Seçenek listesi duyarlı olduğundan tabletlerde, telefonlarda ve hatta basılı materyallerde bile harika görünür. • Tek bir sayfadaki her şey — Kullanıcılarınızın aradıklarını bulmak için bir milyon sayfada arama yapmak zorunda kaldığı günler geride kaldı. Slate, tüm belgeleri tek bir sayfaya yerleştirir. Yine de bağlanabilirlikten ödün vermedik. Siz sayfayı kaydırdıkça, tarayıcınızın karma değeri en yakın üstbilgiye güncellenir. Böylece, dokümandaki belirli bir noktaya bağlantı vermek doğal ve kolaydır. • Seçenek listesi sadece Markdown'dır — Slate ile dokümanlar yazarken sadece Markdown yazmış olursunuz; bu da düzenlemeyi ve anlamayı kolaylaştırır. Her şey Markdown'da yazılır. Kod örnekleri bile sadece Markdown kod bloklarıdır. • Birden çok dilde kod örnekleri yazın — API'nizin birden çok programlama dilinde bağlamaları varsa aralarında geçiş yapmak için sekmelere kolayca yerleştirebilirsiniz. Dokümanınızda, tıpkı GitHub Aromalı Markdown'da olduğu gibi, her kod bloğunun üst kısmında dil adını belirterek farklı dilleri ayırt edebilirsiniz. • 100'den fazla dil için kullanıma hazır söz dizimi vurgulaması, yapılandırma gerekmez. • Otomatik, sayfanın en solunda sorunsuz bir şekilde kaydırılan içindekiler tablosu. Siz kaydırdıkça dokümandaki geçerli konumunuz görüntülenir. Aynı zamanda hızlı. TripIt'teki Slate'i, içindekiler tablomuzda 180'den fazla girişin bulunduğu yeni API'miz için dokümanlar oluşturmak üzere kullanıyoruz. Daha büyük dokümanlarda bile performansın mükemmel kalmasını sağladık. • Kullanıcılarınızın belgelerinizi sizin yerinize güncellemesine izin verin: 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 Sayfaları ile dokümanlarınızı ücretsiz olarak barındırabileceğiniz anlamına gelir. Aynı zamanda, diğer geliştiricilerin, yazım hataları veya başka sorunlar bulduğunda dokümanlarınıza pull isteğinde bulunmalarını da kolaylaştırır. GitHub'ı kullanmak istemiyorsanız dokümanlarınızı başka yerlerde de barındırabilirsiniz. • RTL Desteği Arapça, Farsça (Farsça), İbranice gibi RTL dilleri için tam sağdan sola düzen. Karar Slate, dokümanları oluşturmak için en güçlü açık kaynak yazılımlardan biridir. Danışmanım Chris Myers ile yaptığım tartışmalarda da 4. bölümde seçenek listesini kullanacağım, diğer kısımlarda ise github ve Markdown kullanılacak. Dokümanların daha ayrıntılı bir görünümü aşağıdaki bölümlerde ele alınmaktadır. Teklif edilen dokümanın yapısı SynBioHub Kullanıcı Kılavuzu için bir yapı oluşturdum. Bu yapıyı 2. sayfada bulabilirsiniz. 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 uyacak şekilde güncelleyin. 3. Eski bilgileri kaldırın. 4. Kullanıcı belgelerini daha kolay anlaşılacak şekilde tekrar yazın. 5. Temel biyolojik kavramlara ve SynBioHub'ın arayüzüne dair temel anlayışları artırmak için yeni katkıda bulunanlar için dokümanlara kısa bir ön koşul bölümü ekleyin.