我想用我个人参与开源文档工作的经历来说明，如何从几乎一无所有开始，创建并基于您自己和他人的工作不断发展。
我参与的项目是 Scribus，一个桌面出版 (DTP) 应用程序，用于创建 PDF 以进行印刷或网页出版。大约 10 年前，当我开始为该项目做贡献时，我对它一无所知，因此花了一些时间阅读邮件列表并与之互动，以了解如何使用它。刚开始时，我问了很多愚蠢或茫然的问题，然后逐渐提出更聪明的问题，过了一段时间，我就了解得足以回答别人的问题了。
通过邮件列表源源不断涌入的新用户，很容易看出相同或相似的问题被一遍又一遍地提出。看起来我们——我已经开始感觉自己是这个项目的一部分——可以将这些预期的问题及其答案发布在某个地方。结果是创建了一个 Wiki，供用户为其他用户制作文档。最初，Wiki 是作为非官方信息来源创建的，但随着时间的推移，它因拥有用户想要的可靠、实用的信息而赢得了声誉。对我来说，Wiki 成为了练习编写文档、加入图像以增强文本，以及最重要的是，更多地了解 Scribus 的试验场。就像大多数 Wiki 一样，Scribus Wiki 允许我们编写自己的页面，并编辑和添加到其他人的页面以改善用户体验。当时和现在的大部分灵感都来自邮件列表，无论是通过启动一个新页面还是更新一个旧页面，只要我们看到用户找不到他们需要的东西。
大约在 2008 年，我们注意到经常有人问是否有可以拿在手里的文档——换句话说，一本真正的书。在我最初幼稚地尝试开始写书之后，Christoph Schäfer 加入进来，帮助组织了一项真正的努力，以制作更系统和更合理的文档。大约九个月后，结果是Scribus，官方手册，一本 400 多页的手册，为 Scribus 的 1.3.3.x 版本编写。这项工作最初是在 Wiki 的一个特殊部分完成的，然后导出到 OpenOffice 以便应用样式，然后导出到 Scribus 以进行最终布局。（我们认为，使用其他 DTP 软件来创建 Scribus 手册将是一种亵渎。）
从那时起，以该手册为灵感，我们继续修订和更新 Scribus 附带的在线手册，因此对于一个积极开发的项目来说，这项工作永远不会完成。这对我来说确实是一段奇妙的旅程。
经验教训
以下是我想为那些编写文档的人强调的一些关键教训
- 了解你的主题：除非你了解如何使用软件，而且不仅仅是以某种微不足道的方式，否则你无法充分地编写关于软件的内容。你不仅需要在这方面做自己的工作，而且还需要倾听其他用户，尤其是那些精通该软件的用户。你需要与开发人员互动，尤其是在添加新功能时。同样，你将有机会报告错误或提出修改或新功能的建议。
- 好的写作需要练习：就我而言，练习始于尝试在邮件列表中解释答案，然后为 Wiki 创建更通用的回复。在这个过程中，你会得到关于你写的东西是否有意义、是否简洁，以及希望它对读者是否有趣的反馈。你有机会——并且应该——发展你自己的写作风格。这是 Christoph 和我在编写官方手册时面临的主要挑战之一，即努力在整本书中保持相当一致的风格。而且，当你写到数百页时，你还需要保持它的生动性。阅读关于写作本身的书籍也没有坏处，这样你就可以成为自己和他人的作品的更好编辑。好的写作就是好的写作，无论你在哪里看到它。
- 与他人合作会带来丰富的收获：我不知道如果没有别人的帮助，我是否能够独自完成我已经完成的工作。此外，我所做的工作因为他们的想法和我在这个过程中收到的反馈而变得更好。我很高兴看到我的一些更好的 Wiki 页面被翻译成其他语言，这是你能得到的最好的赞美之一。
访问 Scribus 网站 以了解有关该项目的更多信息，并查看 在线文档，并且不要忘记 Scribus 内部的手册。
2 条评论