我担任 Koha 项目的文档经理已经六年半了，所以当我看到 Sarah White 今年将在 OSCON 上谈论文档时，我就知道我想有机会采访她。
Sarah 将作题为编写让用户满意的文档的演讲。Sarah 相信通过为开源软件编写文档并帮助他人编写文档来帮助用户成功解决他们的问题，我必须同意她的观点，即从事开源项目（不仅仅是编写文档）最美好的部分之一就是结识很棒的人！
在我的采访中了解更多关于 Sarah 的信息。而且，如果您在OSCON 2014，请务必去见见她。
您是如何参与开源的？
我在大学时发现了开源软件，当时我正在处理巨大的 CSV 表格和卫星图像。我的课程和工作需要学术机构和政府机构之间的合作，并找到整合来自大量来源数据的方法。开源项目对于将数据注入专有程序并扩展这些程序的功能绝对至关重要。对我来说，开源始终提供可定制和灵活的解决方案。自从 15 年前参与开源以来，我从未遇到过足够令人信服的理由让我放弃 Linux 操作系统或开源工具。
您为什么创办 OpenDevise？
我与 Dan Allen 共同创办了 OpenDevise，旨在帮助开源项目与其用户和开发社区进行清晰有效的沟通。
您是否为任何开源项目编写（或协助编写）过文档？
我目前正在为 Asciidoctor 项目编写文档，并且我为 Arquillian 和 Fedora 编写了教育内容。
在开源文档项目的工作中，您学到了什么？
记录开源项目非常耗时。但也很有趣和令人振奋。当您为一个项目创建文档时，您就站在了项目维护者和用户之间的交汇点的有利位置。您正在帮助用户成功解决他们的问题，同时与开发人员协作以提高项目的可用性。而编写文档最棒的部分是我可以结识很多很棒的人。
您最喜欢的开源工具是什么？
Fedora，它干净、现代、快速，而且无论我向它扔什么外部设备，它都能正常工作。Arquillian，因为准确的测试是必须的，而且社区是最伟大的社区之一。开源。社区。永远。Git，如果没有版本控制，我会被锁在一个小小的软垫牢房里。Blender 和 darktable，它们让我的生活变得美好，而且功能非常强大。最后，但同样重要的是，是我最喜欢的两个写作工具，gedit 和 Asciidoctor。
Asciidoctor 项目是如何产生的？
2012 年，GitHub 的开发人员开始用 Ruby 实现 AsciiDoc 并开源了这个项目。Matthew McCullough 在那年早些时候向 Dan 和我推荐了 AsciiDoc，当时我们正在评估与 GitHub、GitHub Pages 和基于 Ruby 的静态网站生成器配合良好的标记语言。Dan 和我帮助完成了 Asciidoctor 的第一个兼容版本 (0.1.0)，在 2013 年初，Ryan Waldron 将项目移交给了我们。从那时起，Asciidoctor 社区迅速发展并改进了软件的功能。Asciidoctor 项目现在包含 30 多个存储库——您可以输出 PDF 和幻灯片，使用 JavaScript 实现实时在浏览器中查看您的内容，并与 Gradle 和 Maven 集成。注意：AsciiDoc.py 由 Stuart Rackham 创建。
当一个开源项目缺乏文档时，应该从哪里开始？如何不仅编写文档，还能让社区支持并参与他们的工作？
当一个项目没有文档时，我会与项目维护者聚在一起，了解他们对项目的愿景和目标。与此同时，我会与项目的用户交谈，从他们的角度了解项目。他们使用该项目做什么？他们在哪里以及如何使用它？它如何帮助他们？他们在使用（或尝试使用）项目时遇到了什么问题？
此外，我会收集和分析我可以找到的关于项目的所有内容，例如博客文章、演示文稿、截屏视频等。我还深入研究问题跟踪器、邮件列表、讨论列表、社交媒体提及以及我可以获得的任何分析数据。最后，我会浏览代码并尝试在没有任何帮助的情况下使用该项目。收集所有这些信息的目的是什么？确定用户当前和急迫的痛点。我使用这些痛点来重点编写初始文档，例如 README 文件和教程，以便它回答用户最常见的需求和问题。
您是否发现哪种方法最适合记录软件？小组同时工作，个人文档作者，还是以上某种组合？
我还没有找到记录软件的万能工作流程，因为每个项目及其生态系统都是独一无二的。但我确实知道如何启动这个过程。您必须让关于软件的信息从项目维护者和核心贡献者那里流动起来。他们是未开发的宝贵信息来源，但这些信息往往会卡在他们的脑海中。我为一个成功的项目使用的一种策略是要求维护者和开发人员告诉我他们喜欢他们的软件的一个理由。
我发现了很多需要记录的基本优势和功能。而且现在很多文档以电子邮件回复的形式存在。我只需要构建它。这让我想起了我最喜欢的一句关于这个主题的名言。
大多数人都可以接受写电子邮件。他们不认为这是写作。没有写作障碍。有人问你一个问题，你回复并打字。—Stoyan Stefanov
这让我想到流程的另一个关键部分：使贡献工作流程尽可能基本。尽可能抛弃规则、要求和工具。反正没人喜欢规则。而且它们只是又一件需要编写、编辑和维护的东西。我不了解你，但我宁愿花时间编写代码片段，记录狼獾、外星人和丢失的防御作战手册的冒险经历。
评论已关闭。