经常用Java，C ++或任何其他语言编写的软件代码在编写文档方面颇具挑战性，部分原因是技术编写人员通常尚不精通编程语言。但是，即使对于精通该语言的作者或开发人员，也很难编写代码。没有要遵循的分步过程。代码通常以非线性顺序排列，因此您不能简单地逐行处理代码。还有一个问题，就是要记录多少文件，要涵盖的内容以及在哪里包含文件。总体而言，文档编写代码的最佳实践有些模糊且不确定，这使文档编写代码成为技术编写者面临的最具挑战性和最困难的任务之一。
在上一个主题“编写代码”中，我简要谈到了编写代码的需求。但是，鉴于该主题的重要性，我在此处用其专用主题对本节进行了更深入的扩展。
目录
- 从最近的经验文档代码开始
- 挑战1：代码不遵循分步范例
- 挑战2：受众的技术水平差异很大
- 挑战3：代码需要了解特定的编程语言
- 挑战4：要确保代码示例在各个发行版之间都能正常工作，需要进行大量维护
- 挑战5：工程师对好的代码和不好的代码有更多的了解代码文档的重要性
从最近的经验文档代码开始
我喜欢通过将抽象主题作为实际经验来开始。我最近从事的一个文档项目涉及为Fire TV应用程序创建视频技能-开发后端逻辑以使流媒体应用程序能够进行语音交互，以便用户可以说“播放星际大战”（或其他电影），并且视频可以在其中播放您的应用。
当用户说出这些Alexa命令时，Alexa会解释这些命令，并将信息打包为结构化的JSON请求，该请求会发送伙伴的Lambda代码。Lambda是一项AWS服务，可提供无服务器计算。合作伙伴应该侦听传入的请求，然后开发自己的代码以适当地响应请求，大概是为Instellar检索媒体标识符（在此示例中）并将该媒体标识符发送到其Fire TV应用程序进行播放。该实现涉及对Lambda函数进行编码。
为了帮助开发人员，工程师提供了一个示例Lambda函数（在Node JS中），但没有解释。当我在为此编写文档时，我觉得有必要解释Lambda代码的逻辑。
Lambda代码只有大约450行，而且并不复杂。但是我对Lambda或Node JS并不那么熟悉，所以我对这两者都学到了足够的知识，以了解每一行的状况。在记录代码的方法中，我解释了触发Lambda代码首先被调用的条件。然后，我完整地展示了Lambda代码，以便用户使用上下文。然后，我将代码分成四个离散的逻辑部分。在完整的代码示例下面，我介绍了每个部分（将它们分别标记为“第1部分说明”，“第2部分说明等”），直到完成整个代码示例为止。
这种方法并不是特别好，但是我们有更好的方法。我希望有空间详细说明这些部分，而不仅仅是发表简短的在线注释。您可以在此处查看文档：步骤3：了解Alexa指令和Lambda响应（多模式设备）。毫无疑问，本文档将很快更改，因此，我不愿提供我所描述的方法之外的更多详细信息。但是我在这里将它作为介绍编写代码挑战的介绍。
总体而言，文档代码可能是技术写作中最具挑战性的方面，特别是对于非工程师而言。以下各节说明了为什么文档编写代码会带来如此多的挑战。
挑战1：代码不遵循分步范例代码本身是非线性的。
顶部的功能（例如变量）可能要等到底部的功能才能实现。在底部定义的函数可以在中间的其他代码块内运行，依此类推。当您得到一大堆要记录的代码时，其汇编顺序根本就不明显。
大多数技术作者遵循的中心范例是基于任务的模型，在该模型中，您从第1、2、3步开始，依此类推，直到完成任务为止。代码文档不是这种情况。代码本质上是非线性的。您不能简单地从顶部开始再进行到底部。尽管我在代码解释中尝试了逐节的解释，但我不得不跳过一些行或注意它们是后面各节中解释的逻辑的一部分。
总体而言，这种非线性与技术文档中通常采用的程序方法大不相同。
挑战2：受众的技术水平差异很大
我面临的另一个挑战是决定要解释什么和要跳过什么。开发人员是否已经精通Lambda和Node JS的处理程序？还是像我一样对他们来说这是新事物？
在记录代码时，即使他们的技术水平差异很大，您也必须写给听众他们明白看的懂的知识。但是，当受众的技术水平和领域背景差异巨大时，我们要么通过解释显而易见的内容来覆盖高级开发人员，要么通过假设过多而疏远经验不足的开发人员。
实施渐进式信息披露模型（在其中披露一些信息，然后让它们扩展以获取更多详细信息）可能很棘手。即使受众是技术人员，也无法保证他们在您要记录的特定技术方面具有专业知识。由于所有这些朦胧的结果，我们常常最终把自己想象成观众。
挑战3：代码需要了解特定的编程语言
与上述有关受众多样性的观点有关的事实是，我们的技术作家经常缺乏对编程语言的熟悉。或者，如果我们确实对编程有所了解，那么它并不总是适合该项目的语言。因此，我们马上就处于不利地位，必须逐步学习教程，以了解代码中正在发生的事情的基本知识。
此外，我们没有在记录基础知识，而是在文档中记录了如何在特定上下文中（通常是高级）实施代码。仅假设了解有关代码工作方式的知识。我们几乎必须走进高级微积分课程并解释Legrange乘数，而除了开始学习代数以外，别无其他选择。
挑战4：要确保代码示例在各个发行版之间都能正常工作，需要进行大量维护
另一个挑战是确保代码示例在各个发行版之间都能正常工作。我粘贴了完整的Lambda代码以提供上下文，但是在几周内，我对代码示例进行了一些调整。然后，我不得不更新Lambda代码以及逐节的解释。如果您在整个文档中散布了许多代码示例，那么要在各个发行版之间维护这些代码将很困难。您如何确保它有效？您是否将代码与叙述性上下文分开，以便可以对其进行更常规的测试？
分离代码以启用测试听起来是个好主意，但是一旦您将代码与概念解释分开，您就有可能有人会以不再与解释相符的方式更新代码。
挑战5：工程师对好的代码和不好的代码有更多的了解
最后，我要注意的是，在编写代码时，我感觉有点像局外人在写我不属于的文化或国家。技术作家通常是工程领域的局外人。不是开发人员，我什至没有意识到代码不好。工程师生活和呼吸代码，许多人认为代码是诗歌。
高效的代码技术（例如，根据需要扩展资源的递归循环）可能很漂亮，从而唤起了工程师的美感。以我作为技术撰稿人的观点，我不太可能以同样的敬畏和敬畏态度来对待代码。我更平凡的代码处理方法可能会难以与开发人员用户产生共鸣。
代码文档的重要性
尽管在编写代码方面存在很多困难，但是不应忽视此文档领域。询问开发人员API文档最重要的元素是什么，而您肯定会一次又一次地听到答案是代码示例。包括工作代码示例，开发人员可以轻松地将其复制并粘贴到其文档中。代码示例演示如何将摘要合并到实际实现中。代码示例，示例应用程序-无论采用哪种形式，都可以为我们提供更多代码，代码，代码。在“编写文档”会议上，查看工程师Ruthie Ben Dor的以下视频片段。回答以下问题：“制作API文档的三个最重要的元素是什么？”Ruthie强调需要包含代码示例。
我认为，如果您要制作API文档，则应该包含3件事，或者在制作过程中应该做的3件事。我认为，最重要的是，如果您只是想让人们开始使用它，那就是代码示例。有许多API文档生成器将为您生成代码示例。有时它们不是很好，所以请实际检查并审查这些代码示例以确保它们确实可以正常工作，这是很大的。提供一种方法及其调用方法是一回事，但是对于开发人员而言，必须采用这种方法并弄清楚如何制作有效的代码，并达到目标，这只是一个障碍。与他们只是可以复制并粘贴到浏览器控制台中以证明它对自己有效的做法相反，这是降低进入门槛的一种非常好的方法。代码示例非常庞大，人们可能会在您的API中使用多种语言的代码示例。（Ruthie Ben Dor：API文档和开发者门户网站2/3-YouTube）
为什么工程师如此频繁地说他们想要代码？代码示例展示了如何以实际方式实现抽象的叙述性解释。代码展示了如何在一些可行和有形的目的上使用参考API。从这个意义上讲，代码是一种非常强大的工具，可以帮助用户了解如何使用您的API。尽管代码示例非常重要，但API文档中常常忽略或缺少它们。
毕竟，仅涵盖参考资料并让开发人员弄清楚如何实际地使用它就容易得多。在我的API课程的这一部分中，我将提供具体策略，以成功将代码示例合并到您的文档中。
閱讀更多 沙場點兵見穹蒼 的文章
