执行摘要

昨天在 SciPy 的 Dask BOF 会议上，我们讨论了最近的文档工作以及如何弥补文档中的不足。我们希望制定一个改进策略。

一段时间以来，我们一直在探索将文档迁移到 Diátaxis Framework，在 SciPy 会议上与其他维护者交流后，我们清楚地看到许多项目正趋同于此框架，我们有信心继续沿着这条路走下去。本文阐述了我们将如何利用现有文档并应用该框架，使内容更清晰、更容易查找。注意：这篇博文概述了我们的方向，但变化将是渐进式的。

我们希望文档能快速回答以下问题

• 我知道我的工作流程可以并行化 - Dask 能帮我吗？
• 如何查找特定 worker 的日志？
• 我应该使用 .persist() 吗？

目录

• 理论
• 现有文档
• 新结构
• 您如何提供帮助

理论

Diataxis Framework 建议将文档分为 4 个完全独立的章节。

图片来源： https://diataxis.fr/

每个章节都有其独特的作用。

• 教程 提供一个叙述性的流程，旨在实现一个特定的较大目标，例如预测全球温度或分析金融数据。
• 操作指南 面向那些已经知道做什么，并正试图找出如何做的人。这些人可能会问诸如以下问题：
  • 如何对时间序列应用滚动平均？
  • 如何按列进行 groupby 操作？
  • 如何写入 geotiff 文件？
• 参考 提供某个特定操作的精确参数和输出。
• 解释 提供背景信息并包含操作内部工作方式的描述。

现有文档

有几个不同的网站构成了 Dask 文档的不同方面。特别值得关注的是 示例、教程 和 文档。

我们目前在 文档 上拥有的大部分文档属于“解释”和“参考”类别，但它们相当混杂。其中还散布着一些小的“操作指南”，尤其是在 API 文档中。

教程 上的内容是“教程”和“解释”的混合体。它们回答诸如“我可以用 Dask Dataframes 做些什么？”和“什么是 Dask Dataframe？”之类的问题。这些内容类似于讲座，通常没有引入性的示例，并且假设读者既想学习如何在 Dask 中执行特定操作，也想了解这些操作的工作原理。这类材料可以作为独立内容使用，并在 binder 上运行。

示例 基本属于“操作指南”，但涉及相当多的设置，并且每个示例都没有拆分成足够小的部分。它们回答诸如“如何使用 Dask dataframes？”之类的问题，并且包含一些更长的流程示例。

哪些页面使用最多？

通过 Google Analytics，我们可以看到最常被浏览的页面。

很难确定这些页面是否是可见性最高的页面，或者它们是否确实包含了用户正在寻找的信息。但无论如何，这都传达了导航对于引导用户的重要性。

新结构

教程 将保持原样，并被视为长篇概述。

示例 将更多地以操作指南的形式呈现，减少解释，增加代码。这将类似于您在其他项目中可能看到的图库或食谱风格的文档。从历史上看，示例的现有作用之一是展示 Dask 是什么样子，而这一作用现在已被“10 Minutes to Dask”所取代。

文档 将进行重组，左侧导航栏将大幅精简以提供指导。左侧导航栏的一个想法是

• 安装
• 10分钟上手 Dask (操作指南)
• 教程与讲座 (教程)
• 示例 (操作指南) - 这将是一个着陆页，指向 示例 或 API 参考的各个章节。
• 最佳实践 (解释)

• API (参考)

• 用户指南 (解释)

  • DataFrame - 解释什么是 dataframe - 积极链接到参考文档。
  • 数组
  • Bag
  • Delayed
  • Futures
  • 任务图
  • 调度
  • 诊断仪表盘
• 配置 (参考)
• 部署 Dask 集群 (参考)
• 开发指南 (参考)
• 更新日志 (参考)
• 常见问题 (参考)

许多文档字符串 (即参考) 本身已经包含简短的操作指南文档。我认为这是放置这些内容的好地方，我们可以从其他地方充分链接到这些规范文档。

您如何提供帮助

如果您发现文档中的不足之处，请在 Dask 问题跟踪器上提出问题！我们目前看到的最大空白在于“操作方法”，这些通常通过 Google 搜索找到。因此，如果您搜索如何在 Dask 中做某事，并且正在寻找可直接复制粘贴的示例但找不到，请告知我们。

如果您发现其他不足之处，也请告诉我们。如果您知道您的需求如何契合 diataxis 框架，那就更好了 :)