【Docs 重构计划】重新定义理想的文档 ✨ (original) (raw)

一、背景

Paddle 官网文档是许多开发者接触 Paddle 的第一入口，也是很多贡献者为 Paddle 社区贡献代码的第一步。

打算，目前 Paddle 文档由于自身架构、相关基础设施等方面的设计不合理，导致了诸多问题，如：

• Docs 仓库结构不合理，文档内容管理混乱；
• 文档贡献流程繁琐、踩坑非常多（尤其是格式问题），缺乏开发者友好的自动化工具；
• 文档 CI 对很多格式问题没有进行有效拦截；
• 文档维护成本高，需要大量人力参与 Review；
• ...

以上问题只是冰山一角...😓

相应的，许多社区开发者也对文档体验提出了很多建议，如 @RedContritio 提出的文档构建流程优化 ➡️ PaddlePaddle/community#762

二、目标

对于 Paddle 社区的贡献者，文档不应该成为开发过程中的阻碍；

对于 Paddle 社区的开发者，文档应该提供规范、清晰的信息；

对于 Paddle 社区的维护者，文档应该以易于维护，低成本的保证文档质量；

Important

因此，我们决定号召所有社区开发者，共同参与 Paddle 文档重构工作，重新定义大家心中的文档。
有兴趣的朋友，可以直接在 Issue 区下回复 参与 即可，并未截止时间限制。

三、计划（暂定）

目前具体的开发方案还未敲定。我们期望通过共同讨论的形式，来一步步敲定最终的文档重构方案。这会是一个长期的工作，以便大家持续关注。

目前暂定的大致计划如下，希望能在年前开始启动：

1. 调研好的文档（numpy..），学习优秀方案；
2. 批判 Docs 文档及其脚本，屎山代码赏析；
3. 敲定改进方案。