本页面包含有关 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、GenBank、FASTA 等。互联网上也提供了各种研究论文和一些教程，例如：1. https://pubs.acs.org/doi/abs/10
文档的当前状态：
目前，用户文档位于：“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 部分：
如上所述，可选广告将用于生成此部分的文档。本部分将包含以下端点： 1. 用户端点 2. 搜索端点 3. 下载 Endpoints 4. 下载 Endpoints 5. 提交端点 6. 权限端点。 7. 修改 Endpoints 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 只是 Markdown - 使用 Slate 编写文档时，您只是编写了 Markdown，以便您轻松编辑和理解。所有内容都是用 Markdown 编写的，甚至代码示例只是 Markdown 代码块。• 使用多种语言编写代码示例 - 如果您的 API 具有多种编程语言的绑定，那么，您可以轻松添加标签页，以便在这些编程语言之间切换。在您的文档中，您可以通过在每个代码块顶部指定语言名称来区分不同的语言，就像使用 GitHub Flavored Markdown 一样。• 开箱即用的语法突出显示功能，支持超过 100 种语言，无需任何配置。• 在页面最左侧自动流畅滚动的目录。当您滚动屏幕时，系统会显示您在文档中的当前位置。而且速度也很快。我们使用 TripIt 中的 Slate 为新 API 构建文档，我们的目录包含 180 多个条目。我们确保了性能保持极佳，即使文档较大也是如此。• 让用户为您更新文档 - 默认情况下，您的 Slate 生成的文档会托管在公开的 GitHub 代码库中。这不仅意味着您可以使用 GitHub Pages 免费托管您的文档，还可让其他开发者在发现拼写错误或其他问题时轻松向您的文档发出拉取请求。当然，如果您不想使用 GitHub，也可以将您的文档托管在其他位置。• RTL 支持从右到左的 RTL 语言（如阿拉伯语、波斯语、希伯来语等）采用从右到左的布局。Verdict Slate 是最强大的开源软件之一，可用于生成文档。根据与我的导师 Chris Myers 先生的讨论，我将使用 Slate 作为第 4 部分，而在其他部分则使用 GitHub 和 Markdown。以下各部分介绍了更详细的文档视图。 我为《SynBioHub 用户指南》创建了一份结构，请参阅第 2 页，了解提议的文档的结构。Myers 先生已接受并修改了该结构。项目目标 1. 重构文档。2. 更新文档以适应现代版本的 SynBioHub。3. 移除过时的信息。4. 重写用户文档，使其更易于理解。5. 在帮助新贡献者的文档中添加简短的预备内容部分，帮助他们加深对 SynBioHub 的基本生物概念和界面的基本理解。