Linux 和开源文档一团糟：解决方案如下
当手册过时、不可读或不存在时，仅仅告诉某人 RTFM 并不能解决问题。我们需要提高文档的质量，而实现这一点的方法很简单。
当我还是一个初出茅庐的 Unix 用户和程序员时，对任何技术问题的首选回答都是 RTFM，它代表“阅读 F…精细手册”。不幸的是，这一点对于 Linux 和开源软件一代来说并没有改变。现在是我们解决这个问题并带来积极改变的时候了。手册和几乎所有文档通常都已经过时，有时几乎无法阅读，有时甚至不存在。
我们并不是不知道这个问题。 Jon Corbet 是 LWN 的编辑，LWN 是最好的深入 Linux 出版物和 Linux 内核文档的监督者，自从他从事 Linux 工作以来，他就一直在谈论这个问题。但没有人对此采取任何行动。
或者更确切地说，他们确实这样做了。他们抱怨，抱怨，但是努力吗？就像老鼠给猫敲响铃一样；每个人都在抱怨它，但没有人致力于它。
这不公平。有些人在文档方面下了很大的功夫。他们的数量还远远不够，而那些一直致力于此的人已经精疲力尽了。
事实上，过去四年来一直维护 Linux 手册页项目的 Alejandro Colomar 刚刚退出。为什么？科洛马尔解释说，这很简单，“我一直在业余时间做这件事，根本没有公司赞助这项工作。……我再也无法在经济上维持这项工作了。”
谁能责怪他呢？
正如 Corbet 指出的那样，“我经常抱怨，尽管成千上万的开发人员拿着报酬从事 Linux 内核工作，但没有一个人的工作是为内核编写文档。”
并不是没有人写文档。 Corbet 继续说道，“有很多开发人员编写文档，请不要误会我的意思；他们中的一些人为此付出了很大的努力。但这通常不是他们的雇主付钱给他们的目的。”
这种情况已经持续相当长一段时间了。几年前，Corbet 曾指出“没有人愿意为文档付费”并且“没有人的工作是为内核编写文档”。缺乏专用资源导致文档质量低劣。
这是一个问题。这是一个真正的问题。
特别是，Linux 内核文档非常丑陋。在 2022 年 Linux Plumbers 会议上，Corbett 表示：
当我第一次来维护内核文档时，所有内容都被扔到了主顶级目录中。一位以前的维护者很好地描述了它“无论以前的随机路人把它扔在哪里”。所以我们改进了它，但我们仍然处于一种让我想起我女儿卧室的情况，那里的东西被扔到任何地方。如果你想找到一些东西，那就不太好运了。
从那时起，它变得更好了，但我们可以说，它仍然不适合新人。
内核文档由独立编写的“数千个单独的文档”组成，而不是一个连贯的文档主体，这没有任何帮助。尽管已经努力将文档组织成针对特定读者的书籍，但总体文档仍然缺乏统一的结构。
谷歌软件工程师兼 Linux 内核开发人员 Steve Rostedt 对此表示同意。在去年的 Linux 管道工会议上，他说，“当他遇到错误时，他找不到描述事情如何工作的文档。”如果像 Rostedt 这样资深的人遇到麻烦，你认为一个新手程序员在试图找到一个难题的答案时会有多少运气？
虽然我一直在谈论 Linux，但我向您保证，其他开源项目的情况也没有那么好。其中许多，甚至是受欢迎的，由于资金不足和快速发展而难以维护全面和最新的文档。我的意思是，当您的代码发布在持续集成/持续交付 (CI/CD) 管道中，每天或两天将程序发布到生产环境时，文档永远不会完全是最新的。
但是，我们不是在谈论最新的文档。我说的是针对开发人员、系统管理员和最终用户的基本有用文档和手册。
例如，太多的 GitHub 项目只有一个 README 文件作为文档。那没有帮助。
其他项目似乎并不关心文档。以我最喜欢的 Linux 桌面界面 Cinnamon 为例。许多人使用它并喜欢它，但它没有最终用户网站；它只有 GitHub 页面。现在，Linux Mint 论坛和社区很棒，但您需要认真挖掘才能找到您当前问题的答案。
那么，对此我们能做些什么呢？ OpenSource.com 有一份很好的文档最佳实践列表。
对文档的贡献与代码贡献一样重要。
将文档和代码放在同一个项目存储库中。
使文档成为合并或发布里程碑的要求。
-
对代码和文档有一致的贡献流程。
拥有完善的文档编写流程。
那太棒了。祝大家好运，让人们像重视代码一样重视文档贡献。文档一直是编程中被忽视的孩子。
这是解决方案
您想知道改进开源项目文档的真正秘密吗？
准备好？
付钱给作家。就是这样。
编写文档——无论是 500 页的手册、快速而简陋的操作方法，还是常见问题解答——都是一项艰苦的工作。相信我。我已经完成了所有这些工作，坦率地说，虽然我仍然会时不时地为 linux-terminal.com 撰写操作方法文章，但没有人能给我足够的钱来编写严肃的文档，更不用说技术手册了。工作量太大，钱却不够。
不过，其他人确实有才华和时间。他们没有的是空闲时间。例如，如果有人愿意付钱给科洛马尔，他似乎愿意再次将自己的肩膀放在手动翻页轮上。
因此，如果您真的想帮助 Linux 或您最喜欢的开源项目，请安排向程序员或精通技术的作家支付真金白银来编写文档。科技世界将变得更加美好。