焦外成像项目

本页面包含有关 Google 文档季可接受的技术写作项目的详细信息。

项目摘要

开源组织：

焦外成像

技术文档工程师：

vis_verborum

项目名称：

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

项目时长：

标准时长（3 个月）

Project description

创建、阅读、共享：优化焦外成像的文档

1. 摘要

Bokeh 是一款非常强大的工具，使用 Python 来创建基于浏览器的交互式可视化。它拥有庞大的用户群（每月 conda 下载量达到 50.2 万，PyPi 下载量达到 85.5 万次），并拥有大量贡献者（GitHub 上的 455 位贡献者）。毫无疑问，Bokeh 拥有大量文档是有机增长的。因此，位置不一致、难以访问和复杂化。

Google 的文档季为 Bokeh 文档的结构和内容提供了集中审核和修订功能，也为确保文档和相关工具和工作流的未来做好准备。

我使用 Python 和 Sphinx（最近：PyZillow 和 PyPresseportal）编写并记录了开源项目。但让我成为 Google 《Google 文档季》的独特参与者的原因在于我的新闻专业背景：我在新闻编辑部工作了 13 年多，多年来我担任过总编辑和数字变革的倡导者。除了从事新闻工作之外，我还承担越来越多的职责，包括设计和记录新的数字工具和风格指南，以及培训新闻编辑部员工。

最近我刚从欧洲搬到美国，之后我决定探索一些新的方法，将自己在沟通和编码方面的热情汇聚到一起。我发现技术写作是我的写作和技术方面的技能与经验的最佳组合。在此提案中，我将阐述如何使用 Google 的文档季度优化 Bokeh 的文档：让创建和参与文档工作变得更加便捷，让阅读文档变得更加简单，并更轻松地与他人共享文档中的信息。

2. 现状

Bokeh 的官方文档包含以下主要单元：

• 推介文档：安装指南、用户指南、开发者指南、版本说明
• 资源库和演示（包含源代码的交互式示例）
• 参考指南（基于文档字符串的文档）
• 教程（大量 Jupyter 笔记本，托管在 mybinder.org 上）
• IDE 的文档字符串和模型帮助
• 项目代码库中的示例和 README 文件

此外，Bokeh 支持论坛和 Bokeh 的开发者会在 Stack Overflow 上积极回答用户问题，Bokeh 的 Medium 博客上也提供了大量信息。

大多数文档网页都是通过 Sphinx 创建的，并使用多个标准和自定义 Sphinx 扩展程序。例如，参考指南是使用“autodoc”和自定义的“bokeh_autodoc”等扩展名根据文档字符串生成的。自然扩展的文档的本质是多余的和不一致之处。

在分析现有文档时，我最先注意到的就是文档撰写方面缺乏明确的样式准则。焦外成像开发者指南包含一些基本说明。不过，本文档并未包含有关样式的太多指导，尤其是关于文档字符串以外的文档。因此，样式和结构问题会加大访问文档中信息的难度，尤其是对于新手而言。

例如：

• 使用名词、动名词和不常见的字词，而不是清晰明了、强有力的动词，使某些文本无谓地复杂： “主要的观察结果是，典型的用法涉及使用 person() 函数创建绘制对象”。这应该让阅读更容易。例如：“image() 函数是绘制物体的最常用函数。”
• 有些语句过长，使其难以理解：“接下来，我们可以调用 vbar，将水果名称要素列表作为 x 坐标，将条形高度作为顶部坐标，还可以选择我们希望设置的任何宽度或其他属性”。较长的语句应该拆分为较短的句子或项目符号列表。简化句子对于有阅读障碍的用户或母语不是英语的用户尤其有用（请参阅问题 #10160）。
• 使用的“你”和“我们”不一致，会让用户感到困惑和分散注意力：“根据你的使用情形，可以使用两种基本方法”和“我们可以使用不同的调用绘制全年的数据”（同一页面中的两个示例）。有些页面会以甚至不同的方式向读者显示内容，例如：“用户可能必须安装其他依赖项”或“用户可以创建更复杂的布局”。
• 拼写错误、缺失和多余的字词以及语法错误会打断阅读流程，并破坏信息的可信度：“焦外成像让您能够轻松制作基本条形图”或“请参阅用户指南中的字形部分”。
• 结构上的不一致可能会让读者感到沮丧：例如，在一个网页上提供详细说明了示例的示例，而在另一个网页上对示例进行说明。

Bokeh 的文档着陆页很简短，没有包含所有可用资源的信息（没有提及庞大的文档字符串库和模型帮助函数库、支持论坛、演示版或 Medium 博客）。这也使得新用户更难上手使用焦外成像。

3. 进球数

为了更高效地利用为期 11 周的文档开发阶段，我将着重介绍以下三个关键要素：

3.1. 改进文档创建功能

Bokeh 的大部分文档都是由贡献者编写的，他们将文档添加到针对新功能和 bug 修复的拉取请求中。虽然我会在文档开发阶段使用一些文档开发阶段来编辑和重构现有文档，但我会强调创建和维护文档的工作流能够满足未来需求：贡献者应该尽可能轻松地保持始终如一的高标准文档。

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

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

3.2. 改进文档阅读能力

优秀文档的目标是让当前和潜在用户能够轻松准确找到正确的信息，并尽可能有效地利用这些信息。

文本易用性的关键因素是文本的风格和结构：以清晰、一致的风格撰写文档，让读者可以快速找到所需信息，没有干扰和不必要的语言。文档结构简单透明，便于您快速查找相关信息。

我将着眼于这两个方面，着重介绍对新用户的易用性。其中包括对以用户指南为中心的推介材料进行全面阅读。此外，我还将改进文档着陆页，以便更明确地针对不同的目标受众群体，确保所有用户都能快速找到合适的资源。

就像改进上文所述的文档创建方式一样，我将专注于为未来的改进奠定基础，并持续为 Bokeh 的文档设置高标准。

3.3. 改进文档共享功能

第三方平台上越来越多地讨论焦外成像。其中许多平台都使用元数据（例如 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. 交付成果

总而言之，以下是我预计会在《文档季》中介绍的内容：

• 适用于焦外成像贡献者的文档样式准则
• 修改了 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 的文档季以及文档开发阶段的目标
• 收集焦外成像贡献者的反馈，以进一步优化文档开发阶段的计划

文档开发阶段

第 1 周（9 月 14 日至 9 月 20 日）：

• 开始审核和修改推介材料文档
• 开始起草风格指南

第 2 周（2021 年 9 月 27 日 - 9 月 27 日）：

• 继续完善样式指南
• 继续修改叙述文档
• 开始改进文档着陆页

第 3 周（9 月 28 日至 10 月 4 日）：

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

第 4 周，10/05 - 10/11：

• 完成对推介材料的修改
• 与 Bokeh 核心团队讨论如何在 PR/CI 工作流中集成用于文档质量控制的工具

第 5 周（10 月 12 日至 10 月 18 日）：

• 在 Slack 上安排 Bokeh 贡献者问答会议，讨论风格指南、改进叙事文档，以及 PR/CI 工作流程
• 开始将我现有的 OpenGraph 元数据概念验证开发为可部署的 Sphinx 扩展程序
• 根据焦外成像贡献者问答会话提供的反馈，修改样式准则

第 6 周（10 月 19 日至 10 月 25 日）：

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

第 7 周（10 月 26 日至 11 月 1 日）：

• 测试 Sphinx 扩展程序
• Bokeh 贡献者在 Slack 上的第二次问答环节
• 根据第二次问答环节的反馈修改可交付成果

第 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 日 - 10 月 12 日）：

• 完成并提交项目评估

Google 文档使用季结束后：

• 我希望继续参与 Bokeh 的开发，继续完善 Bokeh 的文档。
• 我计划继续针对 OpenGraph/结构化数据元数据开发 Sphinx 扩展程序。
• 我希望利用自己在新闻领域的背景和现有的网络，宣传 Bokeh 作为数据新闻领域的工具。例如，撰写面向新闻读者的焦外成像简介，或者提供关于在新闻环境中使用焦外成像的会议演讲。

6. 关于我自己

我原来是一名记者，对电视、网络和广播新闻都有自己的背景。我曾在电视和数字新闻领域担任主编及记者，这让我在写作和编辑方面拥有多年的工作经验。与此同时，我参与了多个旨在促进数字化转型和自动化的项目。我撰写了许多涵盖数字工具和工作流程的手册，以及数字新闻品牌的风格指南和沟通策略。我还培训了团队成员如何使用这些工具。

我一直被通信和技术的交集吸引。当我学会用 Python 编写代码时，为我打开了全新的世界：例如，我能够对数据新闻业进行数据分析和可视化。通过学习编程，我还能够积极与软件工程师合作，为新闻编辑室的工作流程开发数字工具。

很遗憾，我在上一份工作时编写的手册和文档还没有公开。因此，我现在的重点是更多地参与开源项目（有关示例，请参阅下文）。我在技术写作方面一直以风格指南（如 Google 的开发者文档风格指南和 Microsoft 风格指南）为基础。我经常使用 GitHub、Slack 和 Linux。我一直在使用 Sphinx、Mypy 和 Sphinx autodoc 等工具编写叙述文档、文档字符串和类型提示。

我目前是自由职业者。在文档开发阶段，我的时间表为 Bokeh 的文档提供了必要的灵活性，每周大约 25 小时。我在太平洋时区工作，但很荣幸能满足团队的日程安排和需求。

7. 近期开源文档示例

• PyZillow：PyZillow 是房地产网站 Zillow.com 的 API 的 Python 封装容器。除了提供一些代码并担任代码维护者之一，我还编写了完整文档。我在叙事文档以及模块参考中使用了 Sphinx。我根据添加到代码中的文档字符串，使用 Sphinx 扩展程序 autodoc 创建了模块引用。

• PyPresseportal：PyPresseportal 是网站 presseportal.de 的 API 的 Python 封装容器。网站 presseportal.de 是德国最大的新闻稿和投资者关系公告发布者之一。例如，几乎所有警察和消防部门都使用此服务来发布新闻稿。作为记者使用以下 API 多年后，我决定开发一个 Python 界面，用来以 Python 对象的形式访问网站上海量的数据资源。我编写了代码以及完整的基于 Sphinx 的文档。