当我还是Unix的新手用户和程序员时，对任何技术问题的回答都是RTFM，它代表“阅读F…Fine Manual”。不幸的是，对于Linux和开源软件一代来说，这一点并没有改变。现在是我们解决这个问题并带来积极变化的时候了。手册和几乎所有的文档都是过时的，有时几乎无法阅读，有时甚至不存在。

　　我们又不是不知道这个问题。Jon Corbet, LWN的编辑，最好的深度Linux出版物和Linux内核文档的监督者，自从他在Linux上工作以来就一直在谈论它。但从来没有人做过什么。

　　或者说，他们确实如此。他们抱怨，他们抱怨，但是努力?这就像老鼠给猫套铃铛；每个人都在抱怨，但没有人去做。

　　这不公平。有些人在文档方面下了很大的功夫。他们的数量远远不够，而那些一直致力于此的人正在耗尽精力。

　　实际上，Alejandro Colomar在过去四年中一直维护Linux手册页项目，他刚刚辞职。为什么?原因很简单，科洛马尔解释说:“我一直在业余时间做这件事，从来没有公司赞助过这项工作。我再也无法在经济上维持这份工作了。”

　　谁能怪他呢?

　　正如Corbet所指出的那样，“我经常抱怨，即使成千上万的开发人员在Linux内核上工作，也没有一个人的工作是为内核编写文档。”

　　并不是没有人写文档。Corbet继续说道：“不要误解我的意思，有很多开发人员编写文档；他们中的一些人在这方面很努力。但这通常不是他们的雇主付钱让他们做的。”

　　这种情况已经存在很长一段时间了。几年前，Corbet曾指出“没有人愿意为文档付费”，“没有人的工作就是为内核编写文档”。缺乏专用资源导致文档质量低下。

　　这是个问题。这是个真正的问题。

　　特别是，Linux内核文档非常丑陋。在2022年Linux管道工会议上，科比特说：

　　从那以后，情况有所好转，但我们可以说，它仍然对新来者不友好。

　　内核文档由孤立编写的“数千个单独文档”组成，而不是一个连贯的文档体，这没有任何帮助。虽然已经努力将文档组织成特定读者的书籍，但总体文档仍然缺乏统一的结构。

　　谷歌软件工程师、Linux内核开发者史蒂夫·罗斯泰特（Steve Rostedt）对此表示赞同。在去年的Linux管道工大会上，他说，“当他遇到bug时，他找不到描述事物如何工作的文档。”如果像Rostedt这样资深的人都遇到了麻烦，那么你认为一个新手程序员在试图找到一个难题的答案时会有多少运气呢?

　　虽然我一直在谈论Linux，但让我向您保证，其他开源项目的情况也没有那么好。由于资金不足和快速发展，其中许多，甚至是受欢迎的，都在努力维护全面和最新的文档。我的意思是，当您的代码发布处于持续集成/持续交付（CI/CD）管道中，每隔一两天就会向生产环境发布程序时，文档将永远不会完全更新。

　　然而，我们不是在谈论最新的文档。我谈论的是对开发人员、系统管理员和最终用户有用的基本文档和手册。

　　例如，太多的GitHub项目只有一个README文件用于文档。这没有帮助。

　　其他项目似乎并不关心文档。以我最喜欢的Linux桌面界面Cinnamon为例。许多人使用它并喜欢它，但它没有一个最终用户网站；它拥有的只是它的GitHub页面。现在，Linux Mint论坛和社区都很棒，但是您需要认真地挖掘才能找到您当前问题的答案。

　　那么，我们该怎么做呢？OpenSource.com有一个很好的文档最佳实践列表。

　　对文档的贡献和对代码的贡献一样重要。

　　将文档和代码放在同一个项目报告中。

　　使文档成为合并或发布里程碑的需求。

　　对代码和文档有一致的贡献流程。

　　有良好的文档化过程来贡献文档。

　　太好了。祝你好运，让人们像重视代码一样重视文档贡献。文档一直是编程中被忽视的孩子。

　　你想知道改进开源项目文档的真正秘诀吗？

　　准备好了吗?

　　付钱给编剧。就是这样。

　　编写文档——无论是500页的手册、简单的操作指南，还是FAQ——都是一项艰苦的工作。相信我。我已经完成了所有这些工作，坦率地说，虽然我仍然会不时地为ZDNET编写指导文章，但没有人会付我足够的钱来编写严肃的文档，更不用说技术手册了。工作太多，钱却不够。

　　然而，其他人确实有天赋和时间。他们没有的是自由时间。以科洛马尔为例，如果有人愿意付钱给他，他似乎愿意再次把自己的肩膀放在手册页轮上。

　　因此，如果您真的想帮助Linux或您最喜欢的开源项目，请安排支付真正的钱给程序员或精通技术的作者来编写文档。科技世界将会变得更好。