Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- National Resource for Network Biology (NRNB)
- {i>Technical writer <i}(Penulis teknis):
- Prubhtej_9
- Nama project:
- Membuat dokumentasi pengguna untuk SynBioHub & mengembangkan tutorial untuk kasus penggunaan tertentu
- Durasi project:
- Durasi standar (3 bulan)
Project description
Abstrak
Dokumentasi pengguna dirancang untuk membantu pengguna akhir menggunakan produk atau layanan. Dokumentasi pengguna yang baik sangat penting karena memberikan sarana bagi pengguna untuk mempelajari cara menggunakan software, fitur, tips, trik, dan juga menyelesaikan masalah umum yang dialami saat menggunakan software. Hal ini juga mengurangi biaya dukungan dan merupakan bagian dari identitas perusahaan produk, yaitu dokumentasi pengguna yang baik adalah tanda produk dan tim developer yang sehat. Tanpa dokumentasi pengguna yang baik, pengguna mungkin tidak tahu cara melakukan hal-hal yang disebutkan di atas secara efektif dan efisien. Dokumentasi pengguna dapat memainkan peran penting dalam memastikan kesuksesan produk karena komunikasi yang baik adalah dan akan selalu menjadi inti dari bisnis atau produk apa pun, dan dokumentasi yang baik hanya mengambil komunikasi tersebut dan menempatkannya dalam framework yang mudah dikelola yang dapat diakses oleh semua orang untuk meraih kesuksesan. SynBioHub adalah repositori desain untuk biologi sintetis. Alat ini tersedia sebagai situs publik dan sebagai software open source. SynBioHub menggunakan Synthetic Biology Open Language (SBOL), standar open source untuk merepresentasikan desain genetik, dan juga memungkinkan berbagi bagian desain dari file GenBank dan FASTA. SynBioHub dapat digunakan untuk memublikasikan library bagian dan desain sintetis sebagai layanan, berbagi desain dengan kolaborator, dan menyimpan desain sistem biologis secara lokal. Data di SynBioHub dapat diakses melalui HTTP API, Java API, atau Python API, yang kemudian dapat diintegrasikan ke dalam alat CAD untuk membangun desain genetik. SynBioHub berisi antarmuka bagi pengguna untuk mengupload data biologis baru ke database, memvisualisasikan bagian DNA, melakukan kueri untuk mengakses bagian yang diinginkan, dan mendownload SBOL, GenBank, FASTA, dll. Berbagai makalah riset dan beberapa tutorial juga tersedia di internet, seperti berikut: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub memiliki beberapa dokumentasi yang hanya terkait dengan API, sedangkan tidak ada dokumentasi untuk GUI.
Status saat ini dari dokumentasi:
Saat ini, dokumentasi pengguna tersedia di :“https://synbiohub.github.io/api-docs/#about-synbiohub “. Ini hanyalah dokumentasi API dan dokumentasi GUI tidak ada yang dapat membantu pengguna menavigasi dalam repositori desain. Selain itu, dokumentasi API juga perlu sedikit diperbarui, dengan beberapa topik tertentu seperti pemecahan masalah khusus tertentu yang mungkin dihadapi pengguna. Meskipun organisasi ini telah merekam beberapa video tutorial, seperti yang ada di sini. Sebenarnya tidak ada dokumentasi tertulis tentang SynBioHub yang dapat memandu pengguna.
Mengapa dokumentasi pengguna yang Anda usulkan lebih baik daripada dokumentasi saat ini? Saya akan membuat dokumentasi GUI dari awal menggunakan github dan {i>markdown<i} seperti yang disarankan oleh mentor, Bapak Chris Myers. Dokumentasi pengguna yang diusulkan akan disusun untuk meningkatkan dan memastikan efisiensi, konsistensi, dan ketenangan pikiran bagi setiap pengguna akhir. Panduan ini akan berisi panduan tertulis dan gambar terkait, termasuk petunjuk dan penjelasan tentang cara menggunakan setiap fitur simulator open source SynBioHub. Selama diskusi dengan Mr. Myers, juga diputuskan bahwa dokumentasi API akan digabungkan dengan GUI dan akan berisi 6 bagian, yaitu bagian ke-6 akan bersifat opsional. Bagian tersebut disebutkan sebagai berikut: 1. Pengantar 2. Petunjuk penginstalan a) Dari image bawaan b) Dari sumber c) Konfigurasi NGINX 3. Petunjuk Pengguna a) Petunjuk terperinci tentang cara menggunakan setiap fitur GUI b) Tutorial untuk kasus penggunaan umum 4. Dokumentasi API - Endpoints bagian 5. Dokumentasi Plugin 6. Pemecahan masalah dan referensi di masa mendatang.
Bagian-1:
Di bagian ini, pengguna akan mendapatkan pengantar mendetail dan berbagai tutorial terkait SynBioHub.
Bagian-2:
Di bagian ini, berbagai cara yang dapat digunakan pengguna untuk menginstal software open source menggunakan berbagai metode, yaitu: a) Dari image bawaan b) Dari sumber c) konfigurasi NGINX
Bagian-3:
Ini adalah bagian paling penting dari dokumentasi dan akan menghabiskan sebagian besar waktu. Di sini, setiap detail kecil akan ditambahkan dalam konteks ke GUI. Seperti yang disebutkan di atas, ada dua masalah utama yang akan dibahas di bagian ini, yaitu petunjuk mendetail tentang cara menggunakan setiap fitur GUI dan beberapa tutorial untuk kasus penggunaan umum.
Bagian-4:
Seperti yang disebutkan di atas, slate akan digunakan untuk membuat dokumentasi bagian ini. Di bagian ini, endpoint berikut akan disertakan: 1. Endpoint Pengguna 2. Telusuri Endpoint 3. Download Endpoint 4. Download Endpoint 5. Endpoint Pengiriman 6. Endpoint Izin. 7. Edit Endpoints 8. Endpoint Lampiran 9. Endpoint Administrasi
Bagian-5:
Di bagian ini, dokumentasi plugin akan disertakan yang sudah ada dalam dokumentasi SynBioHub lama. Bagian ini akan dibagi menjadi dua bagian, yaitu: spesifikasi dan penerapan plugin. Bagian-6: [Opsional] Bagian ini akan berisi daftar error yang sangat umum terjadi yang dialami pengguna serta berisi beberapa petunjuk pemecahan masalah. Sesuai dengan diskusi dengan Mr. Myers, telah diputuskan bahwa bagian ini dapat digabungkan dengan bagian pengantar, jika tidak terlalu panjang. Analisis Saya dan Pak Myers telah berdiskusi tentang cara memperbarui dokumentasi yang ada dan juga menulis dokumentasi baru untuk GUI. Dalam beberapa percakapan tersebut, kami merumuskan tata letak dasar untuk dokumentasi baru yang telah disebutkan di atas dan perkiraan linimasa telah diberikan di halaman 5 di bawah. Sesuai dengan diskusi, saya akan menggunakan github dan markdown untuk membuat dokumentasi untuk setiap bagian kecuali Bagian-4 dokumentasi yang akan menggunakan slate. Slate:- Slate membantu Anda membuat dokumentasi API yang menarik, cerdas, dan responsif. Slate adalah alat berbasis Ruby yang menghasilkan situs statis dokumentasi API tiga panel yang terlihat bagus dari serangkaian file markdown. Game ini dibangun oleh developer bernama Robert Lord pada tahun 2013 saat ia masih magang berusia 18 tahun di perusahaan software perjalanan ‘Tripit’. Saat itu, ia meyakinkan bosnya untuk mengizinkannya menjadikan project tersebut open source dan sisanya adalah sejarah. Slate memiliki fitur berikut: • Desain yang bersih dan intuitif — Dengan Slate, deskripsi API Anda berada di sisi kiri dokumentasi, dan semua contoh kode berada di sisi kanan. Terinspirasi oleh dokumen API Stripe dan PayPal. Slate terlihat responsif, sehingga terlihat bagus di tablet, ponsel, dan bahkan cetak. • Semuanya di satu halaman — Tidak ada lagi saat-saat pengguna harus menelusuri jutaan halaman untuk menemukan hal yang mereka inginkan. Slate menempatkan seluruh dokumentasi di satu halaman. Namun, kami tidak mengorbankan kemampuan penautan. Saat Anda menggulir, {i>hash<i} browser Anda akan diperbarui ke header terdekat, sehingga menautkan ke titik tertentu dalam dokumentasi masih akan dilakukan secara natural dan mudah. • Slate hanyalah Markdown — Saat menulis dokumen dengan Slate, Anda hanya menulis Markdown, yang membuatnya mudah diedit dan dipahami. Semuanya ditulis dalam Markdown — bahkan contoh kode hanyalah blok kode Markdown. • Tulis contoh kode dalam beberapa bahasa — Jika API Anda memiliki binding dalam beberapa bahasa pemrograman, Anda dapat dengan mudah meletakkan tab untuk beralih antarbahasa. Dalam dokumen, Anda akan membedakan berbagai bahasa dengan menentukan nama bahasa di bagian atas setiap blok kode, seperti dengan GitHub Flavored Markdown. • Penyorotan sintaksis siap pakai untuk lebih dari 100 bahasa, tanpa memerlukan konfigurasi. • Daftar isi otomatis yang dapat di-scroll dengan lancar di bagian paling kiri halaman. Saat Anda men-scroll, posisi Anda saat ini dalam dokumen akan ditampilkan. Prosesnya juga cepat. Kami menggunakan Slate di TripIt untuk membuat dokumentasi API baru, dengan daftar isi yang berisi lebih dari 180 entri. Kami telah memastikan bahwa performa tetap sangat baik, bahkan untuk dokumen yang lebih besar. • Izinkan pengguna memperbarui dokumentasi untuk Anda — Secara default, dokumentasi yang dibuat Slate dihosting di repositori GitHub publik. Hal ini tidak hanya berarti Anda mendapatkan hosting gratis untuk dokumen dengan Halaman GitHub, tetapi juga mempermudah developer lain untuk membuat permintaan pull ke dokumen Anda jika mereka menemukan kesalahan ketik atau masalah lainnya. Tentu saja, jika tidak ingin menggunakan GitHub, Anda juga dapat menghosting dokumen di tempat lain. • Dukungan RTL Tata letak kanan-ke-kiri penuh untuk bahasa RTL seperti Arab, Persia (Farsi), Ibrani dll. Verdict Slate adalah salah satu perangkat lunak open source paling canggih untuk membuat dokumentasi. Sesuai dengan diskusi dengan mentor saya, Mr. Chris Myers, saya akan menggunakan slate (layar pemblokir) untuk Bagian-4 dan untuk bagian lainnya, github dan markdown akan digunakan. Tampilan dokumentasi yang lebih mendetail dibahas di bagian bawah. Struktur untuk dokumentasi yang diusulkan Saya membuat struktur untuk Panduan Pengguna SynBioHub yang dapat ditemukan di halaman 2. Struktur ini diterima dan telah diubah oleh Mr. Myers . Tujuan Proyek 1. Susun ulang dokumentasi. 2. Memperbarui dokumentasi agar sesuai dengan versi SynBioHub modern. 3. Hapus informasi yang sudah tidak berlaku. 4. Tulis ulang dokumentasi pengguna agar lebih mudah dipahami. 5. Sertakan bagian prasyarat singkat ke dokumentasi untuk kontributor baru guna meningkatkan pemahaman dasar mereka tentang konsep biologi dasar dan antarmuka SynBioHub.