文档框架
作者：Julia Signell 和 Jacob Tomlinson
执行摘要
昨天在 SciPy 的 Dask BOF（兴趣小组会议）上，我们讨论了最近的文档工作以及如何填补文档中的空白。我们希望制定一个改进策略。
一段时间以来，我们一直在探索将文档迁移到 Diátaxis 框架。在 SciPy 与其他维护者交流后，我们清楚地看到许多项目都在趋向使用此框架，我们对继续这条道路充满信心。本文介绍了我们将如何整合现有文档并应用该框架，以使内容更清晰、更易于查找。注意：这篇博文勾勒出了我们的方向，但更改将逐步进行。
我们希望文档能快速回答以下问题：
- 我知道我的工作流程可以并行化——Dask 能帮到我吗？
- 如何查找特定工作进程的日志？
- 我应该使用
.persist()吗？
目录
理论
Diataxis 框架建议将文档分成 4 个完全独立的章节。
图片来源：https://diataxis.fr/
每个章节都有其独特的作用。
- 教程（Tutorials）提供叙事性内容，旨在解决特定的更大目标，例如预测全球气温或分析金融数据。
- 指南（How-Tos）面向那些已经知道自己想做什么，并正在努力弄清楚如何做的人。这些人可能会问这样的问题：
- 如何对时间序列应用滚动均值？
- 如何按列进行 groupby？
- 如何写入 geotiff 文件？
- 参考（Reference）提供特定操作的准确参数和输出。
- 解释（Explanation）提供上下文并包含对操作内部工作原理的描述。
当前文档
Dask 文档由几个不同的网站组成，涵盖不同方面。特别值得关注的是 示例（Examples）、教程（Tutorials） 和 文档（Docs）。
我们目前在 文档（Docs） 上拥有的大部分内容属于“解释（Explanation）”和“参考（Reference）”，但它们相当混杂。其中也散布着一些小的“指南（How-Tos）”，特别是在 API 文档中。
教程（Tutorials） 上的内容是“教程（Tutorial）”和“解释（Explanation）”的混合体。它们回答诸如“我可以用 Dask Dataframes 做什么？”以及“什么是 Dask Dataframe？”之类的问题。这些内容的风格类似于讲座，通常没有引发兴趣的例子，并且假定读者既想学习如何在 Dask 中执行特定操作，也想了解这些操作的工作原理。这类内容可以作为独立内容使用，并在 binder 上运行。
示例（Examples） 基本属于“指南（How-To）”，但其中有相当多的设置步骤，并且每个示例没有被拆分成足够小的部分。它们回答诸如“如何使用 Dask Dataframes？”之类的问题，并且包含一些较长的工作流程。
哪些页面使用最频繁？
通过 Google Analytics，我们可以看到访问量最多的页面。
很难判断这些页面是曝光度最高，还是它们确实包含了人们正在寻找的信息。但无论如何，这都传达了导航在引导用户方面的重要性。
新结构
教程（Tutorial） 将保持原样，并被视为长篇概述。
示例（Examples） 将更多地呈现为 指南（How-Tos），解释较少，代码较多。这将类似于您在其他项目中看到的画廊或菜谱式文档。历史上，示例当前的一个作用是展示 Dask 的样子，该作用现在由“Dask 十分钟入门”所涵盖。
文档（Docs） 将进行重组，左侧导航将大幅简化以提供方向。左侧导航的一个设想是：
- 安装
- Dask 十分钟入门 (指南)
- 教程与讲座 (教程)
- 示例 (指南) - 这将是一个登陆页，指向 示例 或 API 参考的各个部分。
- 最佳实践 (解释)
-
API (参考)
-
用户指南 (解释)
- DataFrame - 解释 DataFrame 是什么 - 大量链接到参考文档。
- Array
- Bag
- Delayed
- Futures
- 任务图
- 调度
- 诊断面板
- 配置 (参考)
- 部署 Dask 集群 (参考)
- 开发指南 (参考)
- 更新日志 (参考)
- 常见问题 (参考)
许多 docstrings（即 参考）已经包含它们自己的简短 指南 文档。我认为这是一个放置这些内容的好地方，我们可以从其他地方充分链接到这些规范文档。
您如何提供帮助
当您发现文档中的空白时，请在 Dask 的问题跟踪器上提出问题！我们目前看到的最大空白是在“如何做”方面，这些内容通常通过 Google 搜索找到。因此，如果您搜索如何在 Dask 中执行某项操作，并且正在寻找可复制粘贴的示例但找不到，请告诉我们。
如果您看到其他空白，也请告诉我们。如果您知道您的需求如何与 diataxis 框架契合，那就更好了 :)
博客评论由 Disqus 提供支持