asciidoctor_Asciidoctor编码器编写的文档更少

asciidoctor

我担任Koha项目的文档经理已经六年半了，所以当我看到Sarah White今年将在OSCON上谈论文档时，我知道我希望有机会采访她。

莎拉将发表题为“满足用户需求的文档写作”的演讲。 莎拉（Sarah）相信通过帮助并帮助其他人编写开源软件文档来帮助用户成功解决他们的问题，我必须同意她的观点，这是从事开源项目工作的最佳部分之一（不仅仅是编写文档）结识很棒的人！

在与她的访谈中了解有关Sarah的更多信息。 并且，如果您在那里，请确保您在OSCON 2014见面。

您是如何参与开源的？

我上大学时就使用开源CSV表和卫星图像，发现了开源软件。 我的课程和工作需要学术机构与政府机构之间的合作，并寻求整合多种来源数据的方法。 开源项目对于将数据注入专有程序并扩展其功能绝对不可或缺。 对我而言，开源始终提供可定制和灵活的解决方案。 自从15年前开始涉足开放源代码以来，我从未遇到足够令人信服的理由从Linux OS或开放源代码工具转换。

您为什么启动OpenDevise？

我与Dan Allen一起创立了OpenDevise，以帮助开源项目与其用户和开发社区进行清晰有效的沟通。

您是否为任何开源项目编写（或协助编写）文档？

我目前正在研究Asciidoctor项目的文档，并且已经为Arquillian和Fedora编写了教育内容。

查看完整的OSCON演讲者访谈集

您在开源文档项目中学到了什么？

记录开源项目非常耗时。 它也很有趣且令人振奋。 在为项目创建文档时，您会在项目的维护者和用户之间的交汇处获得最大优势。 您正在帮助用户成功解决他们的问题，同时与开发人员合作以改善项目的可用性。 编写文档的最好的部分是我结识了很多很棒的人。

您最喜欢什么开源工具？

Fedora，它干净，现代，快速，并且无论我使用什么外部设备都可以使用。 Arquillian ，因为必须进行准确的测试，而社区是最伟大的社区之一。 开源。 社区。 曾经 Git，如果没有版本控制，我将被锁定在一个小的填充单元中。 Blender和Darktable，它们使我的生活更加美好，并且功能强大。 最后但并非最不重要的一点是我最喜欢的两个书写工具，即gedit和Asciidoctor。

Asciidoctor项目是如何产生的？

在2012年，GitHub的开发人员开始了AsciiDoc的Ruby实现，并开源了该项目。 Matthew McCullough在同年早些时候向Dan和我推荐了AsciiDoc，当时我们正在评估与GitHub，GitHub Pages和基于Ruby的静态网站生成器配合使用的标记语言。 Dan和我在2013年初帮助完成了第一个符合标准的Asciidoctor（0.1.0）版本， Ryan Waldron将该项目移交给了我们。 从那时起，Ascidoctor社区Swift提高并改善了软件的功能。 Asciidoctor项目现在包含30多个存储库-您可以输出PDF和幻灯片，使用JavaScript实现在浏览器中实时查看内容，并与Gradle和Maven集成。 注意：AsciiDoc.py由Stuart Rackham创建。

如果文档中缺少一个开源项目，那么从哪里开始呢？ 如何不仅编写文档，还如何使社区支持和参与他们的工作？

当项目没有文档时，我会与项目维护者聚在一起，找出他们对项目的愿景和目标。 同时，我与项目的用户交谈，并从他们的角度了解该项目。 他们将项目用于什么目的？ 他们在哪里以及如何使用它？ 它如何帮助他们？ 他们在使用（或尝试使用）项目时遇到什么问题？

此外，我收集并分析我可以找到的有关该项目的所有内容，例如博客文章，演示文稿，截屏视频等。我还浏览问题跟踪器，邮件列表，讨论列表，社交媒体提及内容以及我可以获得的任何分析动手。 最后，我遍历代码并尝试在没有任何帮助的情况下使用该项目。 收集所有这些信息有什么意义？ 确定用户当前和急性的痛苦。 我将这些痛点用作关注初始文档（如README文件和教程）的一种方式，因此它可以回答用户最常见的需求和问题。

您是否找到一种最适合记录软件的方法？ 小组同时工作，是个人文档作者，还是上述几种组合？

我还没有找到用于文档编制软件的灵丹妙药工作流，因为每个项目及其生态系统都是独一无二的。 但是我确实知道如何激发这一过程。 您必须从项目维护者和核心贡献者那里获得有关软件的信息。 他们是尚未开发的信息之地，但是信息往往会卡在他们的脑海中。 我用于一个成功项目的策略是让维护人员和开发人员告诉我他们喜欢其软件的一个原因。

我发现了很多基本的好处和功能来记录。 现在，许多文档都以电子邮件回复的形式存在。 我只需要构建它。 这使我想到了我最喜欢的主题之一。

大多数人都可以写电子邮件。 他们不考虑这本书。 没有作家的障碍。 有人问您一个问题，您答复并键入。—Stoyan Stefanov

这使我想到了流程的另一个关键部分：使贡献工作流尽可能基本。 尽可能多地扔掉规则，要求和工具。 无论如何，没人喜欢规则。 而且，它们只是必须编写，编辑和维护的另一件事。 我不了解您，但我宁愿花时间写一些代码片段，以记录黑客，外星人和失去防御性操作手册的历险。

查看完整的OSCON演讲者访谈集。

翻译自: https://opensource.com/life/14/7/asciidoctor-coder-writes-less-documentation

asciidoctor