焦外成像项目

本页详细介绍了 Google 文档季收录的技术文案项目。

项目摘要

开源组织：
焦外成像
技术文档工程师：
vis_verborum
项目名称：
创建、阅读和分享：优化 Bokeh 的文档
项目时长：
标准时长（3 个月）

Project description

创建、阅读和共享：优化 Bokeh 的文档

1. 摘要

Bokeh 是一款功能强大的工具，可让您使用 Python 创建基于浏览器的交互式可视化图表。它拥有庞大的用户群（每月 50.2 万次 conda 下载，85.5 万次 PyPi 下载）和大量贡献者（GitHub 上的 455 名贡献者）。因此，Bokeh 的详尽文档是自然而然发展起来的，这并不令人意外。因此，在某些地方，这些信息不一致、难以访问且复杂。

Google 的文档季为我们提供了一个独特的机会，可以集中审核和修改 Bokeh 文档的结构和内容，并确保文档以及相关工具和工作流程能够适应未来的需求。

我使用 Python 和 Sphinx 编写和记录了开源项目（最近的项目：PyZillow 和 PyPresseportal）。不过，我之所以能参加 Google 文档季，是因为我具备新闻行业的背景：我在新闻机构工作了 13 年以上，多年来担任主编和数字变革倡导者。除了新闻工作职责之外，我还承担着越来越多的设计和记录新数字工具和样式指南的责任，以及培训新闻编辑室员工。

最近从欧洲搬到了美国后，我决定探索新的方式，将我对沟通和编码的热情汇集在一起。我发现，技术写作是将我所擅长的写作和技术技能完美结合的最佳方式。在本提案中，我将阐述如何利用 Google 文档季优化 Bokeh 的文档：通过简化创建和贡献文档的流程、简化阅读文档的流程，以及简化与他人分享文档中信息的流程。

2. 当前情况

Bokeh 的官方文档包含以下主要内容：

  • 说明文档：安装指南、用户指南、开发者指南、版本说明
  • 图库和演示（包含源代码的互动式示例）
  • 参考指南（基于 docstring 的文档）
  • 教程（mybinder.org 上托管的 Jupyter 笔记本的广泛集合）
  • 适用于 IDE 的文档字符串和模型帮助
  • 项目代码库中的示例和自述文件

此外，您还可以在 Bokeh 支持论坛和 Stack Overflow 上找到丰富的信息。Bokeh 的开发者会在 Stack Overflow 上积极解答用户问题，您也可以访问 Bokeh 的 Medium 博客。

大多数文档网页都是使用 Sphinx 创建的，并使用了多种标准和自定义 Sphinx 扩展程序。例如，参考指南是使用“autodoc”和自定义的“bokeh_autodoc”等扩展程序从 docstring 生成的。由于自然生长的文档具有这种特性，因此其中会包含冗余和不一致的内容。

在分析现有文档时，我首先注意到的是，文档编写缺少明确的样式准则。Bokeh 开发者指南包含一些基本说明。不过，本文档并未提供太多有关样式的指导，尤其是关于超出 docstring 范围的文档。因此，文档中存在的样式和结构问题会使用户更难以获取其中的信息，尤其是新手。

例如：

Bokeh 的文档着陆页非常简短，未包含有关所有可用资源的信息（未提及丰富的 docstring 和模型帮助函数库、支持论坛、演示或 Medium 博客）。这也使得新用户更难以开始使用 Bokeh。

3. 目标

为了最有效地利用为期 11 周的文档开发阶段，我将重点介绍三个关键要素：

3.1. 改进文档创建过程

Bokeh 的大部分文档由贡献者撰写，他们会在提交新功能和 bug 修复的拉取请求中附上文档。虽然我会在文档开发阶段花些时间编辑和重构现有文档，但我会重点确保文档创建和维护工作流程具有前瞻性：贡献者应能尽可能轻松地保持始终如一的较高文档标准。

我将通过以下两种方式确保这一点：

  • 我会创建一套简单实用的样式指南，并添加到现有的开发者指南中。这些准则会说明风格、语法和结构。此外，我还会使用 Slack 等内部沟通渠道，确保 Bokeh 的贡献者了解样式指南。我还会为该团队提供一对一培训和问答会。
  • 我将与核心团队合作，寻找一套最适合的文档质量控制工具，并将其添加到 Bokeh 现有的 PR（拉取请求）和 CI（持续集成）工作流中。根据团队的要求，这可能意味着向 Bokeh 的测试套件添加 pydocstyle、priselint 或 sphinxcontrib-spelling 拼写检查等工具，以及预提交设置或 GitHub 操作。我已向我自己的一个开源项目的 GitHub Actions 添加了可行的概念验证。

3.2. 改进文档阅读体验

编写优质文档的目标是让现有用户和潜在用户能够轻松找到所需的信息，并能够尽可能高效地使用这些信息。

文本易用性的关键因素在于其样式和结构：以清晰、一致的样式编写文档，可让读者快速获取信息，而不会受到干扰和多余语言的困扰。文档结构简单透明，可让用户轻松快速地找到相关信息。

我将重点关注这两个方面，并着重介绍新用户的易用性。这将包括对以用户指南为中心的叙事文档进行全面审核。此外，我还将修改文档着陆页，以便更明确地面向不同的目标受众群体，并确保每位用户都可以快速找到合适的资源。

正如上面提到的改进文档的创建方式一样，我将专注于为未来的改进奠定坚实的基础，并使 Bokeh 的文档始终保持高标准。

3.3. 改进文档共享

越来越多的第三方平台上都在讨论 Bokeh。其中许多平台都使用元数据（例如 Facebook 的 OpenGraph）来添加链接的丰富预览。Facebook、Twitter、LinkedIn、Slack 和 iMessage 等服务都使用 OpenGraph。Bokeh 的 Discourse 论坛也使用 OpenGraph 来呈现链接预览。

为了充分利用这项技术，我将向 Bokeh 的 Sphinx 生成网页添加元数据，如问题 #9792 中所述。最有效的方法是使用专用 Sphinx 扩展程序。几天前，我们在 GitHub 上发布了适用于 OpenGraph 数据的 Sphinx 扩展程序的第一个版本。我会利用文档开发阶段的部分时间来改进此扩展程序，以便与 Bokeh 的文档搭配使用。

我还创建了一个概念验证，我在自己的一个开源项目 PyPresseportal 中成功使用了该证明。此扩展程序会自动收集标题、说明、图片和网址等相关信息。然后，将这些信息作为 OpenGraph 代码插入到 Sphinx 生成的 HTML 代码中。

开发此扩展程序的下一步是引入自定义指令，以手动定义 OpenGraph 元数据（类似于 docutil 现有的“meta”指令）。自动生成的元数据仅会用作回退，以防没有可用的手动输入数据。

支持结构化数据要复杂得多，因此我将主要侧重于为 Bokeh 的文档添加高质量的 OpenGraph 元数据。为支持 OpenGraph 而进行的所有工作，同时也为支持结构化数据奠定了基础。

Sphinx 和 ReadTheDocs 社区的成员都表示对开发 OpenGraph 和结构化数据的扩展感兴趣（例如在问题 #1758 和 #5208 中），我将确保与他们密切合作。

4. 交付成果

总而言之，我希望在文档季结束时完成以下成果：

  • 面向 Bokeh 贡献者的文档样式指南
  • 修改了 PR 和 CI 工作流，以添加自动化文档质量控制
  • 经过修改和重组的用户指南
  • 修改后的文档着陆页
  • 文档网页中包含的 OpenGraph 元数据和有效的 Sphinx 扩展程序

此外，我还会在我的个人网站/Medium 或 Bokeh 的 Medium 博客上撰写“文档日志”，记录我在 Google 文档季期间的历程。这也会成为 Google 项目报告的基础。我会尽可能以 GitHub 问题和拉取请求的形式公开完成所有工作。

5. 时间轴

在社区互动阶段之前：我已经积极参与了 Bokeh 的 GitHub 代码库中的几次讨论，并与 Bokeh 的 Google 文档季导师 Bryan Van de Ven 和 Pavithra Eswaramoorthy 联系过。我将积极参与有关 Bokeh 的对话，并通过构建和发布可视化内容进一步熟悉 Bokeh。

社区互动阶段（8 月 17 日至 9 月 13 日）：

  • 了解核心团队，与导师交流以优化项目计划
  • 设置时间表和沟通渠道，以便定期向导师报告进度并征求反馈
  • 积极参与 Bokeh 的 Slack 讨论，让所有感兴趣的 Bokeh 贡献者了解 Google 的文档季活动以及文档开发阶段的目标
  • 收集 Bokeh 贡献者的反馈，以进一步优化文档开发阶段的计划

文档开发阶段

第 1 周，9 月 14 日至 9 月 20 日：

  • 开始审核和修改叙述性文档
  • 开始起草样式指南

第 2 周，9 月 21 日至 9 月 27 日：

  • 继续制定风格指南
  • 继续修改叙述性文档
  • 开始全面改进文档着陆页

第 3 周，9 月 28 日至 10 月 4 日：

  • 完成样式指南
  • 完成文档着陆页

第 4 周，10 月 5 日至 10 月 11 日：

  • 完成编辑叙述性文档
  • 与 Bokeh 核心团队讨论如何在 PR/CI 工作流中集成文档质量控制工具

第 5 周，10 月 12 日至 10 月 18 日：

  • 在 Slack 上与 Bokeh 贡献者设置问答会，讨论样式指南、对叙述性文档的改进以及 PR/CI 工作流
  • 开始将现有的 OpenGraph 元数据概念验证开发为可部署的 Sphinx 扩展程序
  • 根据与 Bokeh 贡献者进行的问答会话中的反馈修改了样式准则

第 6 周，10 月 19 日至 10 月 25 日：

  • 开始测试用于 PR 和 CI 工作流的文件质量控制工具
  • 继续开发适用于元数据的 Sphinx 扩展程序

第 7 周，10/26 - 11/01：

  • 测试 Sphinx 扩展
  • 在 Slack 上与 Bokeh 贡献者举行的第二次问答会
  • 根据第二次问答会话的反馈修改交付成果

第 8 周，11 月 2 日至 11 月 8 日：

  • 部署 Sphinx 扩展程序，并发布经过改进的叙述性文档和文档着陆页

第 9 周，11 月 9 日至 11 月 15 日：

  • 将文档质量控制工具部署到 PR 和 CI 工作流中
  • 更新并发布了《开发者指南》，其中包含风格指南以及 PR 和 CI 工作流增补内容

第 10 周，11 月 16 日至 11 月 22 日：

  • 完成剩余任务

第 11 周，11 月 23 日至 11 月 29 日：

  • 开始撰写项目报告
  • 开始撰写项目评估

项目最终确定阶段

第 12 周，11 月 30 日至 12 月 5 日：

  • 敲定项目并提交项目报告

第 13 周，12 月 3 日至 12 月 10 日：

  • 最终确定并提交项目评估

Google 文档季结束后：

  • 我希望继续参与 Bokeh 的开发，并继续完善 Bokeh 的文档。
  • 我计划继续为 OpenGraph/结构化数据元数据开发 Sphinx 扩展程序。
  • 我希望利用自己的新闻学背景和现有人脉，将 Bokeh 推广为数据新闻领域的工具。例如，在撰写有关 Bokeh 的文章时考虑到新闻界受众群体，或者在会议上发表有关在新闻界环境中使用 Bokeh 的演讲。

6. 关于我自己

我原本是一名记者，拥有电视、在线和广播新闻方面的背景。在电视和数字新闻领域担任总编辑和记者，让我积累了多年的写作和编辑经验。与此同时，我还参与了多个旨在推动数字化转型和自动化的项目。我撰写了大量手册，涵盖数字工具和工作流程，以及数字新闻品牌的样式指南和传播策略。我还培训了团队成员使用这些工具。

我一直被通信与技术的交汇点所吸引。当我学习使用 Python 编程时，一个全新的世界向我敞开了大门：例如，我能够在数据新闻领域进行数据分析和可视化。学会编码后，我还能积极与软件工程师合作，为新闻编辑室工作流程开发数字工具。

很抱歉，我在之前的工作中编写的手册和文档不对外公开。因此，我现在正专注于更多地参与开源项目（见下文中的示例）。我的工作是以风格指南（例如 Google 的开发者文档风格指南和 Microsoft 风格指南）撰写的技术文章。我经常使用 GitHub、Slack 和 Linux。我一直在使用 Sphinx、Mypy 和 Sphinx Autodoc 等工具编写叙述性文档、文档字符串和类型提示。

我目前是自由职业者。我的工作安排非常灵活，在文档开发阶段，我每周可以花大约 25 小时来处理 Bokeh 的文档。我所在的时区是太平洋时间，但很乐意配合团队的时间安排和需求。

7. 最近的开源文档示例

  • PyZillow：PyZillow 是房地产网站 Zillow.com 的 API 的 Python 封装容器。除了提供一些代码并担任代码维护者之一之外，我还编写了完整文档。我使用 Sphinx 编写了说明文档和模块参考文档。我使用 Sphinx 扩展程序 autodoc 创建了模块引用，该引用基于我添加到代码中的 docstring。

  • PyPresseportal：PyPresseportal 是网站 presseportal.de 的 API 的 Python 封装容器。网站 presseportal.de 是德国最大的新闻稿和投资者关系公告分发商之一。例如，几乎所有警察和消防部门都使用此服务传播他们的新闻稿。在从事记者工作多年后，我决定开发一个 Python 接口，以 Python 对象的形式访问网站的丰富数据资源。我编写了代码和整个基于 Sphinx 的文档。