开门见山地说:文档团队不复存在了。
早在 2016 年 8 月,我们成立了一个团队来负责 Rust 的文档工作。以下是最初的描述和动机
Rust 文档团队将负责上面列出的所有事项。具体而言,他们将负责 Rust 项目的以下领域
- 标准库文档
- The Book 和其他长篇文档
- Cargo 的文档
- 错误索引
此外,文档团队还将通过几种方式协助生态系统文档。首先,以咨询的形式:帮助那些希望改进其 crate 文档的人理解如何实现这一目标。其次,监督整个生态系统文档,并确定我们可以贡献并为所有 Rustaceans 产生重大影响的领域。如果 Rust 项目本身的文档很好,但生态系统的文档很糟糕,那么人们仍然会对 Rust 的文档状况感到沮丧,特别是考虑到我们反对“开箱即用”的态度。需要明确的是,这并不意味着拥有生态系统文档,而是通过比仅仅为 Rust 项目本身做贡献更多的方式来贡献。
我们将在 #rust-docs IRC 聊天室协调工作,并根据团队的判断定期召开会议。定期会议对于协调更广泛的目标非常重要;团队成员的参与也很重要。我们每周开会。
当时,所有这些都是迫切需要的。从事 Rust 工作的人不多,文档也不多。
但文档是一件有趣的事情。它实际上是一个横切关注点(cross-cutting concern)。一个团队为大量其他团队编写文档,长期来看并不能真正奏效。短期来看,这绝对是一个必要且不错的策略。如今,这种方式意义不大。让我们再来看看那些最初的资源
- 标准库的文档已经基本完善,当添加新的 API 时,libs 团队会编写一些初始文档。
- 《Rust 程序设计语言》(The Book)由 Steve 和 Carol 维护。
- Cargo 的文档由 Cargo 团队负责(文档团队在这里从未真正提供过帮助。我一直想提供帮助,但几年过去了,这并没有实现)。
- 错误索引描述编译器错误,所以这是编译器团队的工作。
我们还增加了更多的内容
- Rust By Example
- 《rustc 书》和《rustc 指南》
- 参考手册
- The Nomicon
这样的列表还有很多很多。而在这段时间里,团队的成员并没有真正增加;我尝试了几次让人们参与进来,但大多数人就是不喜欢写文档。目前,唯一真正写文档的人是我,而且我最近也没有太多时间。所以自 2018 年 8 月以来,我们就没有召开过文档团队会议。如今也几乎没有文档相关的 RFC 了。因此,这篇博文与其说是宣布文档团队的终结,不如说是描述了当前已经存在的现实。
我仍然会继续进行核心部分和 The Book 的工作。我计划将来提交更多的文档 PR。
我要感谢过去所有加入过团队的人,以及多年来提交文档 PR 的所有人。很多人非常喜欢 Rust 的文档,如果没有你们所有人,这一切是不可能实现的。