如何编写技术文档小小书 XXshu

如果您不是技术作家，但需要创建文档，则此快速指南将帮助您采取正确的方法。仅需6个步骤，即可帮助您计划和组织内容，并避免常见错误。

请注意，这些技巧用于记录产品和服务。如果要求您编写API文档，则将需要其他方法（尽管某些原理是相同的）。

1.考虑为谁写作

第一个技巧是弄清楚您正在为谁写作。如果您不能直接问客户，请与与客户打交道的任何人交谈。向他们询问客户有什么问题，以及他们了解和不了解什么样的术语。

您还可以使用网络上的关键字研究工具来查看人们正在搜索的术语。

不要写产品功能的描述。这对读者不会有太大帮助。相反，请考虑客户可能需要执行的所有任务。您可以通过创建“如何做”任务的列表来解决这个问题。这将是一个不错的开始，但是在编写内容时，请勿在每个主题的开头放置“操作方法”，因为这会使内容难以使用。

如果您不是技术作者，则不太可能了解内容重用功能和信息类型。没关系。除非您被要求实现内容重用，否则您实际上并不需要了解它们，在这种情况下，您将需要技术写作或内容建模培训。

但是您可以做的是编写您的内容，以便将来与技术作家合作。最简单的方法是将每个主题的信息分为三部分- 概念，任务和参考。

在某些技术写作工具中，您可以将它们创建为单独的文件或主题。但是，如果您使用的是Word或基本的编辑器（例如Zendesk中的编辑器），则只需在编写时遵循该结构即可。从概念开始，然后是任务，然后是参考。它适用于大多数类型的文档。

这个很重要。技术文档不是炫耀您大量词汇或丰富技术知识的地方。尽可能使用简单的语言编写，并谨慎使用行话。

不要认为它愚蠢。您正在使更多的人更容易访问该信息。想一想报纸是如何呈现信息的—即使是比较高调的报纸也使用相当朴素的语言。

请记住，您的读者并不真正想要阅读您的内容。他们之所以使用它是因为他们需要解决问题，因此他们越快解决问题就越好。简单的语言可以更轻松快捷地获得答案。它也更容易翻译，也不太可能使英语为第二语言的人感到困惑。

我在用户指南中看到的最大错误之一是，它们的书写方式就像一本书，用户在此按顺序从前到后阅读。没人会读这样的用户指南或网络帮助。人们需要快速且有针对性的答案，因此他们需要能够查找或搜索术语并直接进入该页面。重要的是，该页面上的信息必须是独立的，以使其本身有意义（并指向其他相关页面的链接）。

如果您确实需要读者了解其他主题，请在参考部分中链接到它们。但是，请忽略用户指南中“更早”和“更晚”的概念。每个页面都可能是第一页，您需要从那里直接进行引导。

许多连续的简短句子可能很难读懂。但是长句子也很难阅读。因此，为了使您的内容更具可读性，请尝试以混合为目的。两个简短的句子后跟一个长长的句子通常效果很好。您不必拘泥于此，只需将其用作指导即可。如果一个句子即将达到20个单词，请考虑将其分为两个。

希望这些技巧将帮助您创建更易于访问，更一致和可重用的文档。如果您关注他们，然后将工作传递给专业的技术作家，那么与他们合作的内容将更加容易。

如果您遇到困难，可以尝试雇用技术作家…有愿意帮助的自由职业者（像我一样！）。

谢谢阅读。我是英国切斯特菲尔德的自由技术作家Craig Wright。我会通过客户了解的术语来解释其产品和服务的工作方式，从而为企业提供帮助。