本頁針對 Google 系列文件接受的技術撰寫專案提供詳細資料。
專案摘要
- 開放原始碼機構：
- 國家網路生物學資源 (NRNB)
- 技術文件撰寫者：
- Prubhtej_9
- 專案名稱：
- 製作 SynBioHub 的使用者說明文件，並開發特定用途的教學課程
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要
「使用者文件」旨在協助使用者使用產品或服務。完善的使用者說明文件非常重要，因為它可讓使用者有機會瞭解如何使用軟體、相關功能、提示和秘訣，以及解決使用軟體時的常見問題。而且可降低支援成本，並且是產品的公司身分的一部分。也就是說，良好的使用者文件代表了健康產品和開發人員團隊。如果沒有優質使用者文件，使用者可能就無法有效且有效率地完成上述事項。使用者說明文件有助於確保產品成效至關重要，因為良好的溝通絕對是任何企業或產品的核心。優質的說明文件能有效落實這項溝通，並將其放入易於管理的架構中，讓所有人都能存取所需資料。SynBioHub 是合成生物的設計存放區。無論是使用公開網站，或做為開放原始碼軟體，都可以使用這項工具。SynBioHub 採用合成生物學開放語言 (SBOL)，這是代表基因設計的開放原始碼標準，並允許分享 GenBank 和 FASTA 檔案中的設計零件。SynBioHub 可用來發布合成零件和設計的圖書館 (即服務)、與協作者分享設計，以及將生物系統設計儲存在本機。SynBioHub 中的資料可透過 HTTP API、Java API 或 Python API 存取，然後整合至 CAD 工具，以便建構基因設計。SynBioHub 提供的介面可讓使用者上傳新的生物資料至資料庫、以視覺化方式呈現 DNA 零件、執行查詢以存取所需零件，以及下載 SBOL、GeBank 和 FASTA 等 SBOL、GenBank 和 FASTA 等。您可以在網際網路上取得各種相關的研究論文和部分教學課程，例如：1. https://pubs.acs.org/dobcs0。
文件目前的狀態：
目前這份使用者說明文件可列載於以下網址：「https://synbiohub.github.io/api-docs/#about-synbiohub」。這只是 API 說明文件，且 GUI 說明文件不存在，可協助使用者在設計存放區中進行瀏覽。 此外，API 說明文件還需一點更新，有一些特定主題，例如解決使用者可能遇到的某些特定問題。儘管該機構錄製了一些教學影片，例如這裡的教學影片。完全沒有有關 SynBioHub 的書面使用者文件來引導使用者。
為什麼建議的使用者說明文件有改善空間？我將使用 GitHub 和 Markdown 等指導者 Chris Myers 建議的建議，從頭開始製作 GUI 說明文件。提議的使用者文件的結構主要在於提升，以確保所有使用者的效率、一致性和高枕無憂。其中包含書面指南及相關圖片，包括開放原始碼模擬工具 SynBioHub 各項功能的使用方式和說明。與 Myers 老師的討論期間，我們也決定將 API 說明文件與 GUI 合併，並包含 6 個部分，其中包括第 6 個部分是選擇性的。各節內容如下： 1. 簡介 2. 安裝操作說明 a) 從預先建構的映像檔 b) 從來源 c) NGINX 設定 3. 使用者操作說明 a) 各項 GUI 功能使用方式的詳細操作說明 b) 常見用途教學課程 4. API 說明文件 - 端點第 5 節。外掛程式說明文件 6. 疑難排解和日後參照。
第 1 部分：
在本節中，我們將針對 SynBioHub 向使用者提供詳盡的簡介與各種教學課程。
第 2 部分：
在本節中，使用者可透過各種方法安裝開放原始碼軟體，例如： a) 從預先建構的映像檔 b) 從來源 c) NGINX 設定
第 3 部分：
這是說明文件最重要的部分，會佔用大部分的時間。在這裡，每一分鐘的詳細資料都會新增至統一發票。如前所述，本節主要會解決兩個問題，也就是每項 GUI 功能使用方式的詳細操作說明，以及常見用途的教學課程。
第 4 部分：
如上所述，插入畫面會用來產生這個部分的說明文件。本節將包含下列端點： 1. 使用者端點 2. 搜尋端點 3. 下載 Endpoints 4. 下載端點 5. 提交端點 6. 權限端點。7. 編輯端點 8. 連結端點 9. 管理端點
第 5 部分：
本節將包含舊版 SynBioHub 說明文件中的外掛程式說明文件。本節將細分為兩個部分，分別是外掛程式規格和實作。第 6 部分：[選填] 本節將列出使用者經常遇到的常見錯誤清單，並一併提供疑難排解操作說明。根據與 Myers 先生的討論，我們認為這個章節能與簡介部分合併，如果篇幅不夠長。 Analytics (分析) 先生和我對話，講解如何更新現有說明文件，並撰寫新文件供 GUI 使用。在這些對話中，我們為新文件設計了基本版面配置，而預估時程表請見下方第 5 頁。根據討論內容，我將使用 GitHub 和 Markdown 為每個部分建立說明文件 (使用插入畫面的第 4 部分除外)。 Slate:- Slate 可協助您建立美觀且具回應性的 API 說明文件。Slate 是以 Ruby 為基礎的工具，可從一組 Markdown 檔案產生外觀美觀的三面板式 API 說明文件靜態網站。開發者是開發人員 Robert Lord，在 2013 年在旅遊軟體公司「Tripit」一歲時，18 歲的實習生。他在那時承諾讓老闆開放開放原始碼，剩下的就完成歷史了。 其功能如下：• 簡潔且符合直覺的設計 - 使用 Slate 時，您的 API 說明會顯示在說明文件的左側，所有程式碼範例都顯示在右側。靈感來自 Stripe 和 PayPal 的 API 文件。螢幕採用回應式設計，因此在平板電腦、手機，甚至是平面上都能呈現最佳視覺效果。• 在單一頁面提供所有資訊，使用者如今必須翻成百萬個網頁，才能找到所需資訊。插入畫面將整份說明文件放在單一頁面上。不過，我們尚未犧牲連結性。捲動畫面時，瀏覽器的雜湊值會更新為最近的標頭，因此連結至說明文件中的特定位置依然自然而且很容易。• Slate 僅為 Markdown - 使用 Slate 撰寫文件時，您只需編寫 Markdown，就能輕鬆編輯和理解。所有內容都以 Markdown 編寫，甚至程式碼範例只是 Markdown 程式碼區塊。• 編寫多種語言的程式碼範例：如果你的 API 具有多種程式設計語言的繫結，可輕鬆放入 Tab 鍵並切換。在文件中，您可以在每個程式碼區塊頂端指定語言名稱，就像使用 GitHub Flavored Markdown 一樣。• 內建語法標明功能，適用於超過 100 種語言，且無須進行任何設定。• 自動、流暢地捲動頁面最左邊的目錄。當你捲動畫面時，畫面上會顯示你目前在文件中的位置。速度也太快了。我們使用 TripIt 的 Slate 來建構新 API 的說明文件，其中目錄有超過 180 個項目。我們確保即使文件較大，效能也依然優異。• 讓使用者為您更新說明文件：根據預設，S Slate 產生的說明文件會託管於公開的 GitHub 存放區。這不僅代表您可以免費透過 GitHub 頁面代管文件，還能讓其他開發人員發現錯字或其他問題時，可以輕鬆向文件提出提取要求。當然，如果您不想使用 GitHub，也可以將文件託管於其他位置。• RTL 支援從右到左的版面配置，適用於阿拉伯文、波斯文 (法爾西)、希伯來文等。 「Verdict Slate」是最強大的開放原始碼軟體之一，可用來製作文件。根據我的導師討論，Chris Myers 先生將使用導板做為第 4 部分，其他部分則將使用 GitHub 和 Markdown。以下各節將深入探討說明文件。我針對 SynBioHub 使用手冊 (請見第 2 頁) 建立提案的結構。這個建築結構已由 Myers 先生接受並修改過。專案目標 1. 重組說明文件。2. 根據新版 SynBioHub 更新說明文件。3. 移除過時的資訊。4. 改寫使用者說明文件，讓內容更容易理解。5. 在說明文件中加入簡短的事前準備章節，方便新貢獻者瞭解基本的生物概念和 SynBioHub 介面。