| 领域 | 飞桨文档体验方案 |
|---|---|
| 提交作者 | OneBeaker |
| 提交时间 | 2022-03-20 |
| 版本号 | V1.0 |
| 依赖飞桨版本 | paddlepaddle-gpu==2.2 |
| 文件名 | 20220320_docs_eval_docs.md |
飞桨框架于 2.0 做了大版本改动，如全面支持了动态图训练、更平滑过渡的动静转换等，针对这些功能，Paddle 也新增了对应的使用文档。
希望有人从用户角度关注文档的宏观组织。包括使用指南、应用实践、API 文档等层级的目录组织；以及使用指南内各个文档的内容组织，粒度大致到文档的标题即可。
深度体验飞桨训练功能，并产出一份文档功能体验报告。主要关注文档的宏观组织，分析粒度大致在文档标题层次。
从用户角度体验飞桨，发掘文档体系中可以改善的功能点。
飞桨从 2.0.0 从 1.x 到 2.0 做了较大的功能更新。对应的文档，也随着做出了较大的改动。
飞桨的文档 显式遵循了 https://documentation.divio.com/ 所描述的文档体系。这与 MindSpore 类似。与 PyTorch 不同。这在用户体验上各有特色，给用户不同的感受。
在本次黑客松之前，未见有人发起对飞桨 2.0 之后的文档做充分分析并生成体验报告。
国内外主流框架及其文档组织风格罗列如下：
- TensorFlow：TF 文档 主要分为 learn、tutorial、guide、API 四个分类。
- PyTorch：PyTorch 主要分为 tutorial 和 API 两个分类。
- 飞桨： Paddle 主要分为 使用指南、应用实践、API 与 FAQ 四个分类。
- OneFlow： OneFlow 主要包括了教程与 API 两个分类。
- MindSpore： MindSpore 主要包括了教程、文档、API 三个分类。
PyTorch 作为第一个将动态图模式发扬光大的深度学习框架，目前的文档生态最为丰富，积累了大量的官方、第三方的学习资料。
TensorFlow 最早方便地、较完备地实现了模型预研、训练到工业部署的问题，在此方面积累了丰富的基础组件和用户群体。不过在 API 设计方面，TensorFlow 由于各种原因导致的 API 功能重复、概念复杂，降低了用户体验感受，同时也间接影响到了文档结构的清晰。
其它的主流深度学习框架，都或多或少受到 TensorFlow 与 PyTorch 的影响。
总结而言，影响用户体验的文档、API 接口可以归为以下几个方面：
- 文档的宏观组织是否合理，包括文档的层级结构、分类
- 文档的行文风格是否适当，如文档之间概念是否一致，文档之间的交叉引用是否充分
- 文档的内容，包括是否能清晰传达概念，是否有必备和充分的配套代码
本报告将预计基于以下几方面的体验形成文字：
- 假定用户是新手上路：用户简单了解 PyTorch 或者其它框架，但是还未接触过飞桨，对深度学习的了解也有限，他如何从飞桨文档官网上获取信息上手飞桨。
- 假定用户是初中级算法工程师：用户已经掌握深度学习的基础技能，现有利用 Paddle 搭建模型进行训练、部署等任务的需求，或者有迁移模型的需求。他如何依据飞桨文档官网上的信息，完成任务，并验证正确性。
- 假定用户是开源爱好者：当用户想自发地为飞桨的文档做贡献时，他如何依据飞桨公开的信息，获取到他能参加哪些活动，如何参与到飞桨的开源建设中来。
- 假定用户是专家级贡献者：用户有框架开发能力，或者有自定义框架、拓展框架功能（如自定义算子）的需求，他如何依据公开的信息，参与到飞桨的（定制）开发中。
报告形成的维度包括：
- 文档的宏观组织：依据 https://documentation.divio.com/ 中的文档四象限理论，与其它主流框架做对比，讨论飞桨的文档组织的特点
- 文档的完备性：与其它框架做对比，综合各个框架，看怎样是“完备”的信息，并讨论飞桨的完备度和特点
- 文档的风格特点：在文档的不同分类之间做对比，分析和归纳不同类型的文档（如指南、实践、API 文档等）它们各自应有的结构特点及优势。并讨论现有的各类文档是否足够满足各自归属类别的结构特点、是否充分发挥了应有的优势
- 结合其它用户体验良好的 AI 领域的有关库（如 HuggingFace）做对比分析
因为是报告形式，无 API 接口设计
提交深度体验报告及相关代码（如果有）。具体考量标准和方式以飞桨 RFC 中讨论为准。
对各主流深度学习框架已经有一定了解，需要进一步做细致的体验测试及分析。形成详细的报告文档。
预计整体的工作量在三周内可完成，不会晚于黑客松设定的验收 DDL。
无