开发者技术写作

HTML、CSS、JavaScript、Python、PHP、C++、Dart——有如此多的编程语言，您甚至可能精通其中几种！但当我们旨在编写更多更好的代码时，我们日常语言的写作和沟通方式变得越来越重要……甚至可能被忽视。

我们关于代码以及围绕代码的写作方式，可以说与代码本身一样重要。无论您在这条线上处于什么位置，我们都可以同意，我们的文字有潜力帮助和损害代码的有效性。

在本文中，我想概述这两个看似不同的领域——编程和写作——如何能够结合在一起，将我们的开发者技能提升到一个新的水平。

等等，技术写作？是的，我的确是这个意思。我确实相信，从某种意义上说，我们都是作家。我在这里为您提供一个入门指南，其中包含写作技巧、建议和示例，说明它如何让您成为一名更好的开发者和沟通者。

技术写作无处不在

去年，广受欢迎的 Mac Git 客户端 Tower 背后的团队 对 4000 多名开发者进行了调查，发现近 50% 的开发者每天花费 3-6 个小时编写代码。

是的，这是一项针对非常小众群体的调查，但我相信我们中的许多人都在这个范围内。无论如何，开发者不会 24/7 编写代码，因为正如这项调查所示，我们花费大量时间做其他事情。

这可能包括

• 演示新功能，
• 记录新功能，
• 更新与新功能相关的工单，或
• 积压工作以支持新功能。

当然，总有时间去上厕所和玩 Wordle。

无论如何，我们通常做的大多数事情都涉及与人沟通，例如您的团队、同事、客户、用户和其他开发者。

因此，除了我们通过代码与计算机进行的沟通之外，我们确实花费了大量时间通过文字与人类进行沟通。文字是书面语言。如果我们把文字写得更好，我们的沟通就会更好。当我们沟通得更好时，我们更有可能得到我们想要的东西。

这就是技术写作 101。

而且它甚至没有在这里结束..一些程序员也喜欢制作自己的产品，这意味着他们需要将营销作为其工作的一部分。技术写作在其中也扮演着重要的角色。所以，是的。我认为可以公平地说，技术写作确实无处不在。

什么是好的语法？

有如此多的编程语言，我们最不希望做的就是再学习一门。

语法是英语的一个组成部分，它释放了沟通的全部潜力。它使我们更正式、更专业、更连贯。

让我快速概述一下语言。

英语语法

就像编程语言一样，英语也有一个定义明确的语法，它以单词开始。

单词是英语的基本组成部分，它们分为八类

可以把这些想象成UI组件：它们是可以随意移动的模块化片段，用来构建完整且健壮的句子，就像你可能会将完整且健壮的UI拼凑在一起一样。所有组件都需要一直存在吗？当然不是！使用构建体验所需的片段来组合句子，就像你在使用界面一样。

语气和语调

词汇、标点符号、句子结构和词语选择。这些都是英语的组成部分。我们用它们来分享想法，与朋友和家人沟通，以及向同事发送电子邮件。

但考虑我们信息的声音至关重要。一个感叹号如何完全改变信息语气真是令人惊奇。

1. 我喜欢编程。
2. 我喜欢编程！ :)

很容易将语气与语调混淆，反之亦然。

语气 涉及我们对词语的选择，这取决于上下文。例如，针对初学者的教程更有可能使用俚语和非正式语言来传达友好的语气，而文档则可能以正式、严肃和专业的风格撰写，以便直奔主题。

相同的信息，用两种不同的语气写成

• 有趣：“扩展您的社交网络，并随时了解最新的趋势。”
• 严肃：“在一个最大的社交网络应用和在线招聘市场上找工作。”

意外地写出带有居高临下、冒犯和不专业的语气信息的情况并不少见。这就是语调发挥作用的地方。大声朗读你的信息，请其他人帮你阅读，并尝试不同的标点符号和句子结构。这就是你如何磨练你的语调。

换个角度思考：你的语气不会改变，但你的语调会。你的语气类似于你作为个人的本质，而语调则是你在特定情况下做出的反应。

主动语态和被动语态

一个句子总是包含一个动作发出者、一个动词和一个目标。这些的顺序决定了句子是用主动语态还是被动语态写成的。

在主动语态中，动作发出者放在首位。例如：“CSS 绘制背景。”

使用主动语态的句子比其对应句子更直接。它们更清晰、更简洁、更容易理解——非常适合更专业的语气，可以直奔主题。

在被动语态中，动作发出者放在最后。（看到我做了什么了吗？）这意味着我们的动作发出者——在本例中为 CSS——放在最后，如下所示：“背景由 CSS 绘制。”

读者通常会在脑海中将被动语态转换为主动语态，从而导致更多的处理时间。如果你曾经听说过用主动语态写作更好，这通常就是原因所在。技术作家大部分时间都喜欢使用主动语态，但也有一些例外情况，例如引用研究：“有人认为……”

但这并不意味着你应该始终追求主动语态。如果有效地使用，在同一段落中来回切换——甚至在同一句话中——可以使你的内容更流畅地从一句话过渡到另一句话。

避免错误

语法与语言的结构和正确性有关，没有什么比快速校对你的文档更能做到这一点。消除写作中的拼写错误、语法问题和语义缺陷非常重要。

在本文的结尾，我将向你展示专业人士用来避免写作错误的宝贵工具。显然，如今几乎所有东西都内置了拼写检查器；我们的代码编辑器甚至有拼写检查和代码风格检查插件来帮助防止错误。

但是，如果你正在寻找一个一站式语法工具，Grammarly 是最广泛使用的工具之一。我并没有从中获得任何好处。它只是一个非常棒的工具，许多编辑和作家使用它来编写简洁明了的文章——就像你可能会使用 Emmet、eslint 或任何其他代码风格检查器来编写简洁明了的代码一样。

编写代码注释

我们为其他开发者编写的内容会对我们工作的整体质量产生重大影响，无论是我们在代码中写什么，如何解释代码，还是如何对一段代码进行反馈。

有趣的是，每种编程语言都带有一套标准的功能来编写注释。它们应该解释代码的功能。我的意思不是像这样模糊的注释

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

相反，使用提供更多信息的注释

red *= 1.2 // Apply a 'reddish' effect to the image

这都是关于上下文的。“我正在构建什么样的程序？” 正是你应该问自己的问题。

注释应增加价值

在我们了解什么构成了“好的”代码注释之前，这里有两个懒惰的注释示例

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

请记住，注释的目的是为代码增加价值，而不是重复代码。如果你做不到这一点，最好保持代码原样。这些示例之所以“懒惰”，是因为它们仅仅重述了代码显然正在执行的操作。在这种情况下，注释是多余的，因为它们告诉了我们我们已经知道的事情——它们没有增加价值！

注释应反映当前代码

在大型项目中，过时的注释并不少见；我敢说在大多数项目中都有。

让我们想象一下，David 是一位程序员，也是一个随和的伙伴。David 想按字母顺序（从 A 到 Z）对字符串列表进行排序，因此他在 JavaScript 中做了显而易见的事情

cities = sortWords(cities) // sort cities from A to Z

然后，David 意识到 sortWords() 实际上是从 Z 到 A 对列表进行排序。这不是问题，因为他只需反转输出即可

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

不幸的是，David 没有更新他的代码注释。

现在想象一下，我没有告诉你这个故事，你看到的只是上面的代码。你自然会认为，在运行第二行代码后，`cities` 将按从 Z 到 A 的顺序排序！整个混乱都是由一个陈旧的注释引起的。

虽然这可能是一个夸张的例子，但如果你正在与紧迫的截止日期赛跑，类似的事情可能会（而且经常会）发生。值得庆幸的是，可以通过遵循一个简单的规则来防止这种情况……在修改代码的同时修改注释。

这是一个简单的规则，可以让你和你的团队免受大量技术债务。

既然我们知道了写得不好的注释是什么样的，让我们看看一些好的例子。

注释应解释非惯用代码

有时，做事的自然方法是不对的。程序员可能不得不稍微“违反”标准，但当他们这样做时，建议留下一个小注释来解释他们的理由

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

这很有帮助，对吧？如果你负责审查这段代码，如果没有那个解释情况的注释，你可能会想要进行修改。

注释可以识别未来的任务

使用注释的另一个有用之处是承认还有更多工作要做。

// TODO: use a more efficient algorithm
linearSort(ids)

这样，你就可以专注于你的流程。并在以后的某个日期，你（或其他人）可以回来修复它。

注释可以链接回源代码

所以，你在 StackOverflow 上找到了解决你问题的方案。复制粘贴该代码后，有时最好保留一个指向帮助你的答案的链接，以便你将来可以参考它。

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

这很重要，因为解决方案可能会发生变化。如果代码出现问题，始终了解代码的来源总是一件好事。

编写 Pull Request

Pull Request (PR) 是任何项目的根本组成部分。它们位于代码审查的核心。如果没有良好的措辞，代码审查很快就会成为团队绩效的瓶颈。

一个好的 PR 描述总结了正在进行的更改以及进行更改的原因。大型项目有 Pull Request 模板，例如从 真实示例 中改编的这个模板。

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

避免使用模糊的 PR 标题

请避免使用以下类型的标题

• 修复构建。
• 修复错误。
• 添加补丁。

这些标题甚至没有尝试描述我们正在处理的构建、错误或补丁是什么。关于修复了构建的哪个部分、解决了哪个错误或添加了哪个补丁的一些额外细节，对于与同事建立更好的沟通和协作大有帮助。它可以统一认识并让大家步调一致。

PR 标题通常以 祈使语气 编写。它们是整个 PR 的单行摘要，应该描述 PR正在做什么。

以下是一些好的示例

• 在 NgOptimizedImage 中支持自定义 srcset 属性
• 将图像配置的默认值设置为 75% 的图像质量
• 为所有内置的 ControlValueAccessor 添加显式选择器

避免过长的 PR

一个大型的 PR 意味着一个巨大的描述，没有人愿意审查数百或数千行代码，有时只是为了最终驳回整个内容！

相反，你可以

• 通过 Issues 与你的团队沟通，
• 制定计划，
• 将问题分解成更小的部分，或者
• 使用自己的 PR 分别处理每个部分。

现在是不是干净多了？

在 PR 内容中提供详细信息

与 PR 标题不同，内容是所有细节的存放地，包括

• 为什么要进行 PR？
• 为什么这是最佳方法？
• 该方法的任何缺点，以及如果可能的话解决这些缺点的想法
• 错误或工单编号、基准测试结果等。

报告错误

错误报告是任何项目最重要的方面之一。所有伟大的项目都是建立在用户反馈的基础上的。通常情况下，即使经过无数次测试，最终还是用户发现了大多数错误。用户也是伟大的理想主义者，有时他们会有功能想法；请倾听他们的意见！

对于技术项目，所有这些工作都是通过报告问题来完成的。一个写得好的问题很容易让其他开发者找到并做出响应。

例如，大多数大型项目都带有 模板

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

收集截图

使用你的 系统截图工具 捕获问题。

如果它是 CLI 程序的截图，请确保文本清晰。如果它是 UI 程序，请确保截图捕获了正确的元素和状态。

你可能需要捕获实际的交互来演示问题。如果是这种情况，请尝试 使用屏幕录制工具录制 GIF。

如何重现问题

当错误在程序员的电脑上实时出现时，他们更容易解决它。这就是为什么一个好的提交信息应该附带精确重现问题的步骤。

以下是一个示例

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

提出可能原因

你是发现错误的人，所以你也许可以提出一些关于错误存在的原因的潜在猜想。也许错误只在你遇到特定事件后才会发生，或者也许它只在移动设备上发生。

探索代码库，并可能确定导致问题的原因，这样做也无妨。然后，你的问题将更快地关闭，并且你很可能被分配到相关的 PR。

与客户沟通

你可能是一名独立的自由职业者，或者你可能是小型团队的首席开发人员。无论哪种情况，假设你负责与项目客户进行交互。

现在，程序员的刻板印象是，我们沟通能力差。我们以使用过于专业的术语、告诉他人什么是可能的和不可能的，甚至在有人质疑我们的方法时变得防御性而闻名。

那么，我们如何减轻这种刻板印象呢？询问客户他们想要什么，并始终倾听他们的反馈。以下是如何做到这一点。

提出正确的问题

首先确保你和客户在同一页面上

• 你的目标受众是谁？
• 网站的目标是什么？
• 你最接近的竞争对手是谁，他们在做什么做得对？

提问也是一种积极写作的好方法，尤其是在你不同意客户的反馈或决策的情况下。提问迫使对方支持自己的主张，而不是你通过维护自己的立场来攻击他们。

• 即使这会带来额外的性能成本，你是否同意？
• 移动组件是否有助于我们更好地实现目标？
• 很好，谁负责在发布后维护它？
• 你知道这两种颜色之间的对比是否通过了 WCAG AA 标准吗？

问题更无辜，并且会促进好奇心而不是敌意。

推销自己

如果你正在向潜在客户推销，你需要说服他们聘用你。客户为什么要选择你？指定以下内容很重要

• 你是谁
• 你做什么
• 为什么你适合这份工作
• 你所做相关工作的链接

一旦你获得工作并需要起草合同，请记住，没有什么内容比一堆法律术语更令人望而生畏了。尽管它是为设计项目编写的，但Contract Killer可以作为编写更友好内容的一个不错的起点。

你对细节的关注可能是你与其他试图赢得同一项目的开发人员之间的区别。根据我的经验，客户同样乐于聘用他们认为合作起来很愉快的开发人员，而不是技术上最称职或最有经验的开发人员。

编写微文案

微文案是编写用户友好型UI消息（例如错误消息）的艺术。我敢打赌，作为开发人员，你肯定遇到过需要编写错误消息的情况，因为它们一直被推迟到发布时才处理。

这可能是我们有时会看到类似这样的错误的原因

Error: Unexpected input (Code 693)

错误是你最不希望用户遇到的问题。但它们确实会发生，我们对此无能为力。以下是一些提高你的微文案技能的技巧。

避免使用专业术语

大多数人不知道服务器是什么，而100%的程序员都知道。这就是为什么在错误消息中看到不常见的术语（例如API或“超时执行”）并不罕见的原因。

除非你面对的是技术型客户或用户群，否则你的大多数用户可能都没有上过计算机科学课程，也不知道互联网是如何工作的，以及为什么某些特定的事情无法正常工作。因此，出现了错误。

因此，好的错误消息不应该解释为什么某些事情出了问题，因为这样的解释可能需要使用令人费解的技术术语。这就是为什么避免使用专业术语非常重要的原因。

永远不要责怪用户

想象一下：我正在尝试登录你的平台。所以我打开浏览器，访问你的网站，并输入我的详细信息。然后我被告知：“你的电子邮件/密码不正确。”

尽管认为这条消息具有敌意似乎有点夸张，但它潜意识里让我觉得自己很愚蠢。微文案指出，永远不应该责怪用户。尝试将你的消息更改为不那么指责性的内容，例如这个改编自Mailchimp登录的示例：“抱歉，该邮箱密码组合不正确。我们可以帮助你找回帐户。”

我还想补充一点，避免使用全部大写字母和感叹号的重要性！当然，它们可以用来表达兴奋，但在微文案中，它们会对用户产生敌意感。

不要让用户感到不知所措

在你的微文案中使用幽默是一个好主意！它可以缓和气氛，并且是缓解即使是最糟糕的错误造成的负面情绪的简单方法。

但如果你没有完美地使用它，它可能会被理解为居高临下且对用户不尊重。这只是一个巨大的风险。

Mailchimp说得很好

不要刻意去讲笑话——强迫性的幽默可能比没有幽默更糟糕。**如果你不确定，就保持严肃的表情。**

（我的强调）

编写可访问的标记

我们可以轻松地用一整篇文章来讨论可访问性以及它与技术写作的关系。哎呀，可访问性通常包含在内容风格指南中，包括微软和Mailchimp的内容风格指南。

你是一名开发人员，可能已经了解了很多关于可访问性的知识。你甚至可能是那些更加勤奋的开发人员之一，他们将可访问性作为工作流程的核心部分。尽管如此，令人难以置信的是，可访问性考虑因素被搁置一旁的情况有多么普遍，无论我们都知道创建包含所有能力的无障碍在线体验有多么重要。

因此，如果你发现自己正在将其他人的文案内容实现到你的代码中、为其他开发人员编写文档，甚至自己编写UI文案，请注意一些基本的可访问性最佳实践，因为它们完善了所有其他关于技术写作的建议。

例如

• 在可能的情况下使用语义标签（例如<nav>、<header>、<article>等）
• 遵循逻辑的标题结构
• 为图像添加替代文本
• 注意内联语义（Mandy Michael有一篇关于这方面的精彩文章）

Andy Bell提供了一些相对简单的方法来使内容更易于访问，值得你花时间去查看。此外，仅仅是为了好玩，John Rhea展示了一些巧妙的编辑技巧，当我们使用语义HTML元素时，这些技巧是可能的。

结论

以上是六种展示技术写作和开发如何相互关联的方式。虽然示例和建议可能不是什么高深莫测的东西，但我希望你发现它们有用，无论是在与其他开发人员合作、维护自己的工作、在紧急情况下需要自己编写文案，甚至起草项目建议等方面。

底线是：提高你的写作技能并投入一些额外的精力到写作中实际上可以让你成为一名更好的开发人员。

技术写作资源

如果你对技术写作感兴趣

• 技术写作建议（Chris Coyier）
• Google的技术写作指南
• 技术写作基础（GitLab）
• UX写作：学习指南（Nielson Norman Group）
• Write the Docs（技术写作社区）

如果你对文案撰写感兴趣

• 文案撰写101（Copyblogger）
• 什么是文案撰写？（Ionos）
• SEO文案撰写指南（Semrush）
• 文案撰写仍然是写作（卫报）

如果你对微文案感兴趣

• 微文案简介（UX Planet）
• Apple的人机界面指南
• Microsoft的写作风格指南
• Mailchimp内容风格指南

如果你对使用专业的风格指南来改进你的写作感兴趣

• MLA写作风格指南
• AP写作风格指南
• APA写作风格指南
• 芝加哥写作风格指南

如果你对无障碍写作感兴趣

• 提高网站内容的可读性（Andy Bell）
• 15个提高网站可访问性的实践（Bruce Lawson）
• 无障碍测试工具（Chris Coyier）
• 为什么开发人员不重视无障碍性？（Melanie Sumner）
• 命名事物以提高可访问性（Hidde de Vries）