开发人员技术写作

HTML、CSS、JavaScript、Python、PHP、C++、Dart - 有这么多的编程语言，你甚至可以完全流利地使用其中的几种！ 但随着我们的目标是编写更多更好的代码，我们用日常语言编写和交流的方式变得越来越重要……甚至可能被忽视。

我们编写代码和围绕代码编写的方式可以说与代码本身一样重要。 不管你在哪条线上，我们都同意我们的话有可能帮助和损害代码的有效性。

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

等等，技术写作？ 是的，这正是我的意思。 我真的相信我们都是某种意义上的作家。 我在这里为您提供一个入门知识，其中包含编写技巧、建议和示例，以了解它如何使您成为更好的开发人员和沟通者。

技术写作无处不在

去年，流行的 Mac Git 客户端 Tower 背后的团队， 对 4,000 多名开发人员进行了调查 并发现近 50% 的人每天花费 3-6 小时编写代码。

是的，这是一项针对相当小众群体的调查，但我想我们中的许多人都属于这个范围内的某个地方。 无论如何，开发人员不会 24/7 全天候编写代码，因为正如本次民意调查所表明的那样，我们正在花费大量时间做其他事情。

这可能包括：

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

当然，总是有时间去洗手间和 Wordle。

无论如何，我们通常做的大部分事情都涉及与您的团队、同事、客户、用户和其他开发人员等人进行交流。

所以我们确实花了很多时间与人类交流 话 除了我们与计算机的交流之外 码. 文字是书面语言。 如果我们写得更好，我们会更好地沟通。 当我们更好地沟通时，我们更有可能得到我们想要的东西。

那是技术写作 101。

而且它甚至还没有到此结束。一些程序员还喜欢制作自己的产品，这意味着他们需要将营销作为工作的一部分。 技术写作在这方面也发挥着重要作用。 是的。 我认为可以说技术写作是很公平的 的确 到处。

什么是好的语法？

有这么多编程语言，我们最不想做的就是学习另一种。

语法 是英语不可或缺的一部分，它释放了沟通的全部潜力。 它使我们更加正式、专业和连贯。

让我简要介绍一下语言。

英语语法

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

单词是英语的基石，它们分为八类：

想想这些像 UI 组件：它们是模块化的部分，你可以移动它们来构建一个完整而健壮的句子，就像你可以拼凑一个完整而健壮的句子一样 UI. 是否所有组件都需要一直存在？ 当然不是！ 将一个句子与完成体验所需的部分组合起来，就像使用界面一样。

声音和语气

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

但关键是要考虑 声音 我们的消息。 一个感叹号可以完全改变消息的语气，真是令人惊讶：

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

很容易将声音与音调混淆，反之亦然。

音色 是关于我们选择单词的问题，这取决于上下文。 例如，针对初学者的教程更有可能使用俚语和非正式语言来传达友好的声音，而文档可能以正式、严肃和专业的方式编写，以努力直截了当。

相同的信息，用两种不同的声音写成：

• 乐趣： “扩展您的社交网络并随时了解当前趋势。”
• 严肃的： “在最大的社交网络应用程序和在线就业市场之一上寻找工作。”

不小心写出傲慢、冒犯和不专业的信息并不罕见。 这是哪里 音 进场。 大声朗读您的信息，让其他人为您阅读，并尝试使用您的标点符号和句子结构。 这就是你如何磨练你的语气。

这是另一种思考方式：你的声音永远不会改变，但你的语气会改变。 您的声音类似于您作为一个人的身份，而语气则是您在特定情况下的反应方式。

主动和被动语态

一个句子总是包含一个演员、一个动词和一个目标。 它们出现的顺序决定了句子是以主动语态还是被动语态书写。

演员排在第一位 主动语态. 例如：“CSS 绘制背景。”

使用主动语态的句子比对应的句子更直接。 它们更清晰、更短、更易于理解——非常适合直截了当的更专业的声音。

随着 被动语态，演员排在最后。 （看看我在那里做了什么？）这意味着我们的演员——在这个例子中是 CSS——在结尾是这样的：“背景是由 CSS 绘制的。”

读者通常会在脑海中将被动语态转换为主动语态，从而增加处理时间。 如果您曾经听说用主动语态写作更好，这通常就是原因。 科技作家大多数时候更喜欢主动语态，只有极少数例外，例如引用研究：“有人建议……”

但这并不意味着您应该始终争取积极的声音。 如果有效使用，即使在同一段落中，从一个句子切换到另一个句子也可以使您的内容更无缝地从一个句子流到另一个句子。

避免错误

语法就是关于语言的结构和正确性，没有什么比快速校对文档更好的了。 消除您的作品中的拼写错误、语法问题和语义缺陷非常重要。

在本文的最后，我将向您展示专业人士用来避免书写错误的宝贵工具。 显然，现在几乎所有东西都有内置的拼写检查器。 我们的代码编辑器甚至有拼写检查和 linting 插件来帮助防止错误。 

但是，如果您正在寻找所有语法的一站式工具， grammarly破解 是使用最广泛的工具之一。 我没有得到任何回扣或任何东西。 它只是一个非常棒的工具，许多编辑和编写者使用它来编写干净和清晰的内容——类似于你可能使用 Emmet、eslint 或任何其他 linter 来编写干净和清晰的代码。

编写代码注释

我们为其他开发人员编写的东西会对我们工作的整体质量产生重大影响，无论是我们在代码中编写的内容、我们如何解释代码，还是我们如何对一段代码提供反馈。

有趣的是，每种编程语言都带有一组标准的功能来编写评论。 他们应该解释代码在做什么。 我的意思不是像这样模糊的评论：

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 想要按字母顺序从 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)

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

现在想象一下，我没有告诉你这个故事，你看到的只是上面的代码。 你自然会认为在运行第二行代码之后，`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

这很重要，因为解决方案可能会改变。 知道你的代码来自哪里总是好的，以防万一它坏了。

编写拉取请求

拉取要求 (PRs) 是任何项目的基本方面。 它们是代码审查的核心。 如果没有好的措辞，代码审查很快就会成为团队绩效的瓶颈。

一个好的 PR 描述总结 什么 正在做出改变并且 为什么 它正在制作中。 大型项目有一个拉取请求模板，就像这个改编自 真实的例子:

## 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% 图像质量
• 为所有内置 ControlValueAccessors 添加显式选择器

避免长时间 PRs

大 PR 意味着一个巨大的描述，没有人愿意审查成百上千行代码，有时只是为了结束整个事情！

相反，您可以：

• 通过与您的团队沟通 问题,
• 制定一个计划，
• 将问题分解成更小的部分，或
• 单独处理每一件作品 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 标准？

问题更加天真，并促进了对仇恨的好奇心。

推销自己

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

• 你是谁
• 你做什么
• 为什么你很适合这份工作
• 您已完成的相关工作的链接

一旦你得到这份工作并需要写一份合同，请记住，没有比一堆法律术语更令人生畏的内容了。 尽管它是为设计项目而写的， 合同杀手 可以成为编写更友好的东西的一个很好的起点。

你对细节的关注可能是你和另一个试图赢得同一个项目的开发人员之间的区别。 根据我的经验，与技术上最有能力或最有经验的人相比，客户会很容易地聘请他们认为会喜欢与之合作的开发人员。

写微文

显微镜 是用户友好的写作艺术 UI 消息，例如错误。 我敢打赌，作为开发人员，有时您必须编写错误消息，因为它们一直被搁置到启动时间。

这可能就是为什么我们有时会看到这样的错误：

Error: Unexpected input (Code 693)

错误是您希望用户处理的最后一件事。 但它们确实发生了，我们对此无能为力。 这里有一些技巧可以提高您的显微复制技能。

避免使用技术术语

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

除非您与技术客户或用户群打交道，否则您的大多数用户可能没有上过计算机科学课程，也不知道 Internet 是如何工作的，也不知道为什么某个特定的东西不起作用。 因此，错误。

因此，一个好的错误信息不应该解释 为什么 出了点问题，因为这样的解释可能需要使用可怕的技术术语。 这就是为什么避免使用技术术语非常重要的原因。

永远不要责怪用户

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

尽管认为这条信息充满敌意似乎很戏剧化，但它下意识地让我感到愚蠢。 Microcopy 说，责怪用户是绝对不行的。 尝试将您的消息更改为不那么挑剔的内容，例如这个示例改编自 Mailchimp 的登录信息：“抱歉，电子邮件密码组合不正确。 我们可以帮助您恢复您的帐户。”

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

不要压倒用户

在你的微文案中使用幽默是个好主意！ 它可以减轻情绪，并且是一种简单的方法来抑制由最严重的错误引起的消极情绪。

但是如果你不使用它 完美，它可能会给用户带来屈尊和侮辱的印象。 那只是一个 大 承担的风险。

Mailchimp 说得很好：

[D] 不要特意开个玩笑——强迫幽默比没有幽默更糟糕。 如果不确定，请保持正视.

（强调我的）

编写可访问的标记

我们可以很容易地花一整篇关于可访问性以及它与技术写作的关系的文章。 哎呀，可访问性通常包含在内容样式指南中，包括那些 微软 和 Mailchimp.

您是一名开发人员，并且可能已经非常了解可访问性。 您甚至可能是更勤奋的开发人员之一，他们将可访问性作为工作流程的核心部分。 尽管如此，令人难以置信的是，可访问性考虑被置于次要位置的频率仍然令人难以置信，无论我们都知道提供包含所有能力的可访问在线体验有多重要。

因此，如果您发现自己在代码中实现了别人的文案，为其他开发人员编写文档，甚至编写 UI 复制自己，注意一些基本的可访问性最佳实践，因为它们完善了技术写作的所有其他建议。

像：

安迪贝尔提供了一些相对 您可以做一些小事情来使内容更易于访问，值得您花时间检查一下。 而且，只是为了踢球， John Rhea 展示了一些巧妙的编辑技巧 当我们使用语义 HTML 元素时，这是可能的。

结论

这些是展示技术写作和开发如何一致的六种方式。 虽然这些示例和建议可能不是火箭科学，但我希望您发现它们很有用，无论是与其他开发人员合作、维护自己的工作、必须在紧要关头编写自己的副本，甚至起草项目提案等等事物。

底线：提高你的写作技巧并在你的写作中付出一些额外的努力实际上可以让你成为一个更好的开发者。

技术写作资源

如果您对技术写作感兴趣：

如果您对文案感兴趣：

如果您对显微文案感兴趣：

如果您有兴趣使用专业的风格指南来改进您的写作：

如果您有兴趣为可访问性写作：