Docs 文档吐槽大会 💬

[sunzhongkai588]

背景

Note

本次活动为 【Docs 重构计划】重新定义理想的文档 ✨ 的前置环节，欢迎大家积极参与。

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

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

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

活动描述

基于以上背景，我们希望在 PFCC 例会上举办一次吐槽大会，让大家全方位、无死角的“喷”一下目前 Paddle 文档存在的问题（不用客气，言辞越激厉越好 🐶）

你可以选择以下或其他任意视角进行抨击：

• 文档使用体验
• 文档开发体验
• 文档维护体验
• 优秀开源文档
• ...

我们希望能够让更多开发者参与讨论，不论你是否了解过 Paddle 文档，都可以提出你的意见，一起共同改进💪。

参与方式

大家可以首先参与先在 docs 仓库下提 issue 记录下你的吐槽

• Issue 标题

  【Docs 文档吐槽大会】+ 一句话吐槽

• Issue 内容

  吐槽点：

  1. xxx
  2. xxx
  3. xxx

  优化建议/想法（如有）：

然后再在本 Issue 区下回复，附上你的吐槽 issue 链接。

你们的吐槽和建议，我们将会在 2024-01-11 PFCC 例会上进行讨论。（是 2024 年的第一场 PFCC例会哦 🎉 快来参与吧）

[GreatV]

• 【Docs 文档吐槽大会】优化建议 docs#6459

[megemini]

PaddlePaddle/docs#6462

[jzhang533]

从 Docs 仓库到官网展示的工具链当中，有部分工具未开源。

如果我记得没错的话，从 Docs 仓库，到官网的展示的 toolchain 中，只有前置的部分脚本开源在了 Docs 仓库。 docs-build.sh 这个脚本只是个入口，还有些脚本，是打包在了镜像里，没有在 Docs 仓库中维护。

Proposal

1. 将整个 toolchain 中用到的脚本，都开源到 Docs 仓库中。
2. 不依赖任何的 docker 镜像，就可以在本地构建出来文档。
3. review 所有的构建脚本，看是否有可以优化的地方。
4. 除了可在官网发布外，也可以发布在 readthedocs 。

Docs 仓库的中文文档，应该只是对英文版本文档的翻译。

现在依然存在中文文档缺失、跟英文文档相比不一致，等问题。

Proposal

1. 构建中文文档时，对于存在英文文档，但是暂时还没写中文文档的，在中文文档页面直接展示其英文文档。
2. 提供一个工具，自动化的，准备出来一份文档，其内容是英文的，文档工程师，只需要在工具产出的产出物里进行翻译工作，减少手工的创建文档、填写文档结构等工作。

官网的文档展示的优化

尽管现在也还不错，但是还有优化的空间，比如配色之类的。 另外，代码高亮好像是有些不太对？

[gowy222]

没有一个月读不透文档...比读研写论文都难...

[SigureMo]

工具链过于陈旧

• Paddle 使用的 Sphinx 是某个上古时期的 Sphinx，且无人推动升级（正常，现状就是这边没人维护）
• Paddle 使用的 markdown 渲染工具已经是一个多年前就弃用的 recommonmark 了，人家已经推荐改用 MyST-Parser 替代，一旦替代将会彻底解决诸如无法引用 Markdown、Markdown 无法渲染表格等问题，一年半以前就和梦师傅说了偏不听哼 fix some cn_docs format issues docs#5277 (comment)

中英文难以做到真正同步

• 从格式上来看，docs 目前中文采用 rST 直接书写交由 Sphinx 渲染，而英文则是使用 docstring 书写，使用 gen_doc.py 生成基本目录结构后利用 Sphinx autodoc 和 napoleon 扩展渲染，两者渲染不可能一致，体验上很差
• 从内容上来看，两者书写规范不一致，而且存储 repo 不一致，没有工具强制化检查，很容易改了一侧而另一侧没有修改，而且想要在 PR 里同步也很麻烦，一般是先提交 Paddle 侧英文 PR，并在中文 PR 使用 PADDLEPADDLE_PR=xxxxx 的方式，从之后的长期维护角度来看，我建议将「中文 API 文档元数据」存放在 Paddle 维护

那么以上问题是否有解决方案呢？当然是有的啦，上述两个问题分别会在目前计划 dokyu 的第二、第一阶段解决，目前在梳理中，详细计划之后会分享～

框架 3.0 时代，我们 docs 也应该有 2.0 了～

[ooooo-create]

文档体验

1. 中英文转换不好，在英文界面没有跳转会中文的选项
2. edit on github 不会跳转，不流畅
3. 什么样的东西(函数，文档...)，使用链接引用而不是``的简单引用，不清晰

仓库

1. 文档结构不够清晰
2. 过时文档多，维护时，需要修改的东西也分散
3. 想要本地构建预览
4. 想要现代化一点的 ci 检查(doge，或者现代化一点的文档生成(doge

期待 docs 2.0 ~