本頁面包含 Google 技術文件季度接受的技術寫作專案詳細資料。
專案摘要
- 開放原始碼組織：
- 美國國家網路生物學資源 (NRNB)
- 技術文件撰稿者：
- Prubhtej_9
- 專案名稱：
- 為 SynBioHub 建立使用者說明文件，並針對特定用途開發教學課程
- 專案長度：
- 標準長度 (3 個月)
Project description
摘要
「使用者」說明文件旨在協助使用者使用產品或服務，良好的使用者說明文件非常重要，因為它能讓使用者瞭解如何使用軟體、軟體功能、提示、技巧，以及解決使用軟體時遇到的常見問題。也有助於降低支援成本，而且是產品企業身分的一部分，例如優質的使用者文件，代表產品以及開發團隊健康。 如果使用者未提供優質的說明文件，使用者就可能無法迅速有效地執行上述操作。使用者文件是確保產品成功的關鍵要素，因為良好的溝通是任何企業或產品的核心要務，而優秀的說明文件只需與客戶溝通，並打造一個易於管理的架構，就能邁向成功。 SynBioHub 是合成生物學的設計存放區。同時以公開網站和開放原始碼軟體的形式提供。SynBioHub 使用 Synthetic Biology Open Language (SBOL)，這是用來表示基因設計的開放原始碼標準，也允許從 GenBank 和 FASTA 檔案分享設計元件。您可以使用 SynBioHub 將合成零件和設計的程式庫發布為服務，與協作者分享設計，以及在本機儲存生物系統的設計。您可以透過 HTTP API、Java API 或 Python API 存取 SynBioHub 中的資料，然後將資料整合至 CAD 工具，以建立基因設計。
文件目前狀態：
目前的使用者說明文件可在以下網址取得：「https://synbiohub.github.io/api-docs/#about-synbiohub」。這只是 API 說明文件，目前沒有 GUI 說明文件，因此無法協助使用者在設計存放區中瀏覽。此外，API 說明文件也需要進行一些更新，包括一些特定主題，例如使用者可能會遇到的特定問題的疑難排解。雖然該機構已錄製一些教學影片，例如這部影片。目前沒有任何 SynBioHub 使用者說明文件，無法為使用者提供指引。
您提出的使用者說明文件為何比目前的版本更優？我會按照導師 Chris Myers 的建議，使用 GitHub 和 Markdown 從頭開始建構 GUI 說明文件。我們建議的使用者說明文件將以結構化的方式呈現，以便提升效率、確保一致性，並讓所有使用者安心使用。檔案包含書面指南和相關的圖像，包括開放原始碼模擬工具 SynBioHub 各項功能的使用說明和說明。在與 Myers 先生討論的過程中，我們也決定將 API 說明文件與 GUI 合併，並且包含 6 個部分，其中第 6 部分將為選用部分。這些部分如下所述： 1. 簡介 2. 安裝說明 a) 從預先建構的映像檔 b) 從原始碼 c) NGINX 設定 3. 使用者操作說明：a) 各項 GUI 功能的詳細使用說明 b) 常見用途教學課程 4. API 說明文件 - Endpoints 部分，第 5 節。外掛程式說明文件 6. 疑難排解和日後參考。
第 1 部分：
在本節中，我們將為使用者提供 SynBioHub 的詳細介紹和各種教學課程。
第 2 部分：
本節將說明使用者可透過各種方法安裝開放原始碼軟體的各種方式，包括： a) 從預先建構的映像檔 b) 從原始碼 c) NGINX 設定
第 3 部分：
這是文件中最重要的部分，也是耗費時間最多的部分。在此，每個細節都會加入 GUI 的內容中。如上所述，本節將主要討論兩個問題，即如何使用每項 GUI 功能的詳細說明，以及一些常見用途的教學課程。
第 4 部分：
如上所述，Slate 會用於產生此部分的說明文件。本節將涵蓋下列端點： 1. 使用者端點 2. 搜尋端點 3. 下載端點 4. 下載 Endpoints 5. 提交端點 6. 權限端點。 7. 編輯端點 8. 連結端點 9. 管理端點
第 5 部分：
本節將納入舊版 SynBioHub 說明文件中已有的外掛程式說明文件。本節將分為兩個部分，分別是外掛程式規格和實作。第 6 部分：[選用] 這個部分會列出使用者經常遇到的錯誤，並提供一些疑難排解指示。根據與 Myers 先生的討論結果，我們決定將這一節與介紹部分合併，前提是不會太長。分析 Myers 先生和我討論了如何更新現有說明文件，以及為 GUI 撰寫新的說明文件。在這些討論中，我們為上述新說明文件擬定了基本版面配置，並在下方第 5 頁提供預估時程。根據討論內容，我將使用 GitHub 和 Markdown 建立每個章節的說明文件，但會使用插入畫面的第 4 部分除外。Slate：Slate 可協助您建立精美、智慧且回應迅速的 API 說明文件。Slate 是一種以 Ruby 為基礎的工具，可從一組 Markdown 檔案產生外觀精美的三個面板 API 說明文件靜態網站。這個程式是由開發人員 Robert Lord 於 2013 年在旅遊軟體公司「Tripit」18 歲時擔任實習生。他在當時說服老闆，讓他願意開放開放原始碼，讓其他物件繼續建構，並擁有歷史沿革。 其功能如下：• 簡潔直覺的設計：Slate 會將 API 說明放在說明文件的左側，所有程式碼範例則放在右側。靈感來自 Stripe 和 PayPal 的 API 說明文件。由於 Slate 是回應式設計，因此在平板電腦、手機甚至平面媒體上都會呈現最佳效果。• 所有內容都顯示在單一頁面：使用者不再需要搜尋數百萬個網頁，才能找到所需內容。Slate 會將整份文件放在單一頁面上。不過，我們並未犧牲連結功能。捲動畫面時，瀏覽器的雜湊值會更新為最接近的標頭，因此說明文件中特定時間點的連結仍然自然且簡單。• Slate 僅僅是 Markdown — 使用 Slate 撰寫文件時，您只是在寫出 Markdown 之後，就可以輕鬆編輯和理解內容。所有內容都是以 Markdown 撰寫，甚至程式碼範例也只是 Markdown 程式碼區塊。• 以多種語言編寫程式碼範例：如果您的 API 有多種程式設計語言的繫結，您可以輕鬆放入分頁，在不同語言之間切換。在文件中，您可以透過在每個程式碼區塊頂端指定語言名稱，區分不同的語言，就像 GitHub 風格的 Markdown 一樣。• 支援 100 多種語言的即用語法醒目顯示功能，無須設定。• 頁面最左側的自動流動目錄，可流暢捲動。捲動時，它會顯示你在文件中的目前位置。而且速度也很快。我們目前正使用 TripIt 的 Slate 來建立新 API 的說明文件，因為我們的目錄有超過 180 個項目。我們已確保即使是較大的文件，效能也能維持在高水準。• 讓使用者為您更新說明文件 - 根據預設，Slate 產生的說明文件會託管在公開的 GitHub 存放區中。這不僅表示您可以使用 GitHub Pages 免費代管文件，還能讓其他開發人員在發現錯字或其他問題時，輕鬆向您的文件提出提取要求。當然，如果您不想使用 GitHub，也可以在其他地方代管文件。• RTL 支援：支援阿拉伯文、波斯文、希伯來文等 RTL 語言的完整由右至左版面配置。 判決結果：Slate 是產生說明文件最強大的開放原始碼軟體之一，根據與導師 Chris Myers 的討論，我會在第 4 部分使用 Slate，其他部分則會使用 GitHub 和 Markdown。如要進一步瞭解說明文件，請參閱下列各節。建議的說明文件架構。我已為 SynBioHub 使用者指南建立架構，請參閱第 2 頁。這個結構體已通過審查，並由 Myers 先生修改。專案目標 1. 重新建構說明文件。2. 更新說明文件，以符合 SynBioHub 的最新版本。3. 移除過時的資訊。4. 重新編寫使用者說明文件，讓內容更容易理解。5. 在提供給新貢獻者的說明文件中，加入簡短的事前準備一節，提升他們對基本生物概念的基本知識和 SynBioHub 介面。