本页面包含 Google 文档季接受的技术写作项目的详细信息。
项目摘要
- 开源组织：
- 国家网络生物学资源 (NRNB)
- 技术文档工程师：
- Prubhtej_9
- 项目名称：
- 为 SynBioHub 创建用户文档，并针对特定用例开发教程
- 项目时长：
- 标准时长（3 个月）
Project description
摘要
用户文档旨在协助最终用户使用产品或服务。优质的用户文档非常重要，因为它为用户提供了了解如何使用软件、软件的功能、提示和技巧，以及解决使用软件时遇到的常见问题的途径。它还可以降低支持成本，并成为产品企业形象的一部分，也就是说，优质的用户文档是产品和开发者团队健康发展的标志。 如果没有优质的用户文档，用户可能不知道如何有效且高效地完成上述操作。用户文档在确保产品成功方面可以发挥关键作用，因为良好的沟通始终是任何业务或产品的核心，而优质的文档只需将这种沟通置于一个可管理的框架中，让每个人都能访问，从而取得成功。 SynBioHub 是一个合成生物学设计库。它既可作为公开网站提供，也可作为开源软件提供。SynBioHub 使用合成生物学开放语言 (SBOL)，这是一种用于表示基因设计的开源标准，还允许共享 GenBank 和 FASTA 文件中的设计部分。SynBioHub 可用于将合成部件和设计库作为服务发布、与协作者共享设计，以及在本地存储生物系统设计。您可以通过 HTTP API、Java API 或 Python API 访问 SynBioHub 中的数据，然后将其集成到 CAD 工具中以构建基因设计。SynBioHub 包含一个界面，供用户将新的生物数据上传到数据库、可视化 DNA 部分、执行查询以访问所需的部分，以及下载 SBOL、GenBank、FASTA 等。互联网上还提供了各种研究论文和一些教程，例如：1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub 有一些文档，但仅与 API 相关，而没有 GUI 文档。
文档的当前状态：
目前，用户文档位于“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 文档 - 端点第 5 节。插件文档 6. 问题排查和日后参考。
第 1 部分：
在本部分中，我们将向用户提供有关 SynBioHub 的详细介绍和各种教程。
第 2 部分：
本部分介绍了用户可以使用各种方法安装开源软件的各种方式，即： a) 从预构建映像安装 b) 从源代码安装 c) NGINX 配置
第 3 部分：
这是文档中最关键的部分，会占用大部分时间。在这里，我们将在 GUI 上下文中添加每一个细节。如上所述，本部分主要介绍了两个方面，即有关如何使用每个 GUI 功能的详细说明，以及一些常见用例的教程。
第 4 部分：
如上所述，slate 将用于生成本部分的文档。本部分将包含以下端点： 1. 用户端点 2. 搜索端点 3. 下载端点 4. 下载端点 提交端点 6. 权限端点。 7. 修改端点 8. 连接端点 9. 管理端点
第 5 部分：
本部分将包含旧版 SynBioHub 文档中已有的插件文档。本部分将分为两个部分，即插件规范和实现。第 6 部分：[可选]此部分将列出用户经常遇到的常见错误，并包含一些问题排查说明。根据与 Myers 先生的讨论，如果时间不会过长，我们已决定将此部分与介绍部分合并。 分析人员 Myers 先生和我曾就如何更新现有文档以及如何为 GUI 编写新文档进行对话。在几次对话中，我们为上述新文档制定了基本布局，并在下文第 5 页提供了预计时间表。 根据讨论内容，我将使用 GitHub 和 Markdown 为各个部分（其中将使用可选广告的第 4 部分除外）构建文档。 可选广告：- 可选广告可帮助您创建美观、智能、响应迅速的 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 Flavored 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 界面的基本了解。