技术文档写作是什么

至少在Red Hat文档团队中，专业作家几乎总是单独处理文档。 但是，您是否尝试过将写作作为一对的一部分？ 在本文中，我将解释配对编写的一些好处。

什么是双人写作？

结对写作是指两个作者在同一房间，同一文本上实时工作。 这种方法提高了文档质量，加快了写作速度，并允许作者相互学习。 结对写法的概念是从结借用的。

进行配对写作时，您和您的同事一起处理文本，提出建议并根据需要提出问题。 同时，您正在观察彼此的工作。 例如，在一个人写作的同时，另一位作家观察了诸如结构或上下文之类的细节。 通常，围绕文档的讨论会变成分享经验和观点，以及就一般写作进行集思广益。

在任何时候，写作都只能由一个人完成。 因此，您只需要一台计算机，除非您希望一位作家进行在线研究而另一人从事写作。 文本工作流程与单独工作相同：文本编辑器，文档源文件，git等。

结对写作实践

我和我的同事Aneta Steflova在Red Hat Enterprise Linux系统管理文档和Red Hat Identity Management文档上完成了超过50个小时的配对编写工作。 我发现与单独写作相比，成对写作：

• 同等生产率或更高生产率；
• 提高文件质量；
• 帮助作家分享技术专长； 和
• 更有趣。

速度

两位作家写一篇文字？ 听起来一半生产率，对吗？ 错误。 （通常）

结对写作可以帮助您更快地工作，因为两个人可以解决更大的问题，这意味着在此过程中被阻止的频率降低。 例如，有一次我们编写了用于身份管理的紧急API文档。 我至少知道Web API的基础知识，REST协议等，这些知识帮助我们加快了文档的这些部分。 Aneta独自工作，可能需要经常打断写作过程才能研究这些主题。

质量

措辞或句子结构不佳，材料不一致等在四只眼睛的检查下很难生存。 例如，我们的一对书面文档由一位极其关键的开发人员审阅，该开发人员以发现技术上的不准确性和不良的结构而闻名。 经过特别的审查后，他说：“完美。非常感谢。”

分享专业知识

我们每个人都生活在自己的写作泡沫中，我们通常不知道其他人如何写作。 配对写作可以帮助您改善自己的写作过程。 例如，Aneta向我展示了如何更好地处理开发人员提供了起始文本的工作（相对于作家使用他们自己的主题知识从头开始写作），我没有经验。 此外，她还对文档进行了彻底的构造，我也开始这样做。

再举一个例子，我对Vim足够精通，可以使XML编辑（例如标签操作）愉快而不是费力。 Aneta看到了我如何使用Vim，被问到了问题，经历了学习过程中的痛苦，现在利用了对我有帮助的Vim功能。

结对写作对帮助和指导新作家特别有用，它是结识专业人士（并与他们同乐）的好方法。

当一对写作闪耀

除了我已经列出的好处之外，结对写作还特别适合：

• 使用 ：Bugzilla可能很麻烦，并且会引起问题，特别是对于那些笨拙的管理人员（例如我）。
• 审查现有文档 ：当需要扩展或固定文档时，有必要首先检查现有文档。
• 学习新技术 ：作家可以比工程师更好。
• 向开发人员发送带有选择问题的电子邮件/信息请求 ：这项任务的难度与您所记录的技术难度成正比。

而且，通过成对写入，反馈是实时的，按需的和双向的。

不利的一面是，成对写作的速度可能更快，从而使作家减少思考主题或措辞的时间。 另一方面，成对写完之后，通常不需要同行评审。

注意事项

要充分利用成对写法：

• 做好充分准备的项目，否则您可能会浪费同事的时间。
• 健谈的类型需要专注于任务，否则他们最终会说话而不是写作。
• 准备直接反馈。 结对写作不适用于对反馈过敏的作家。
• 当心会话劫持者。 占主导地位的性格可以将旁观者的成对写作变成独奏。 （但是，只要经验不足的伴侣从劫机者那里学习，或者经验丰富的作家正在向劫机者提供反馈，则有时一个人接管可能会很好。）

结论

结对写作是一次会议，但实际上您可以完成工作。 这项活动使作家能够专注于我们职业中不可或缺的一件事-写作。

这篇文章是在与Aneta Steflova结对写作的帮助下撰写的。

翻译自:

技术文档写作是什么