HTML、CSS、JavaScript、Python、PHP、C++、Dart--有这么多的编程语言，你甚至可能完全精通其中的几种但是，当我们的目标是写出更多、更好的代码时，我们用日常语言写作和交流的方式变得越来越重要......甚至可能被忽略了。

我们写代码和围绕代码的方式可以说和代码本身一样重要。尽管你在这条线上的位置，我们都可以同意，我们的语言有可能帮助和伤害代码的有效性。

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

等等，技术写作？是的，这正是我的意思。我真的相信我们在某种意义上都是作家。我在这里给你介绍写作的技巧、建议和例子，让你知道如何使你成为更好的开发者和沟通者。

技术写作无处不在

去年，流行的Mac Git客户端Tower背后的团队对4000多名开发者进行了调查，发现他们中近50%的人每天花3-6小时编写代码。

是的，这是一项调查，调查的是一个相当小众的群体，但我想我们中的许多人都属于这个范围。不管怎么说，开发人员并不是24小时都在写代码，因为正如这项调查所表明的，我们花了很多时间做其他事情。

这可能包括。

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

当然，也总有时间上厕所和做Wordle。

总之，我们通常做的大多数事情都涉及到与人沟通，如你的团队、同事、客户、用户和其他开发人员。

因此，除了通过代码与计算机交流外，我们确实花了很大一部分时间通过文字与人交流。言语是书面语言。如果我们把字写得更好，我们就能更好地交流。当我们沟通得更好时，我们就更有可能得到我们想要的东西。

这就是技术写作101。

而且这还没有结束。一些程序员也喜欢制作自己的产品，这意味着他们需要把营销作为他们工作的一部分。技术写作在这方面也起着巨大的作用。所以，是的。我认为可以很公平地说，技术写作确实无处不在。

什么是好的语法？

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

语法是英语的一个组成部分，它能充分释放交流的潜力。它使我们更正式，更专业，更有条理。

让我给你简单介绍一下语言的情况。

英语句法

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

词语是英语的组成部分，它们分为八个类别。

把这些想象成UI组件：它们是模块化的部件，你可以随意移动，以构建一个完整而强大的句子，就像你可能拼凑一个完整而强大的UI一样。是否所有的组件都需要一直在那里？当然不需要。用你完成体验所需的部分来组装一个句子，就像你组装一个界面一样。

语音和语调

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

但是，考虑我们信息的声音也是至关重要的。一个感叹号就能完全改变一条信息的语气，这很神奇。

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

我们很容易将声音与语气混淆，反之亦然。

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

同样的信息，用两种不同的声音来写。

• 乐趣。 "扩大你的社交网络，并保持对现在流行的东西的更新。"
• 严肃： "在最大的社交网络应用和在线就业市场之一寻找工作"。

不小心写出的信息被认为是居高临下、具有攻击性和不专业的，这种情况并不罕见。这就是语气发挥作用的地方。大声阅读你的信息，让其他人为你阅读，并尝试使用你的标点符号和句子结构。这就是你如何磨练你的语气。

这里有另一种思考方式：你的声音永远不会改变，但你的语气会改变。你的声音类似于你是谁，而语气是你在特定情况下的反应。

主动语态和被动语态

一个句子总是包含一个演员、一个动词和一个目标。这些东西的顺序决定了该句子是以主动语态还是被动语态书写的。

在主动语态中，行为主体是第一位的。例如。"CSS画了背景"。

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

使用被动语态，演员是最后一个。(看到我所做的了吗？）这意味着我们的演员--本例中的CSS--是在最后的，就像这样。"背景是由CSS绘制的"。

读者通常会在头脑中把被动语态转换成主动语态，从而导致更多的处理时间。如果你听说过用主动语态写作会更好，这通常是原因所在。技术作家在大多数时候都喜欢用主动语态，只有极少数例外，如引用研究。"有人建议，......"

但这并不意味着你应该总是争取使用主动语态。如果有效地使用，从一种到另一种的转换--甚至在同一段落中--可以使你的内容从一个句子到另一个句子更加顺畅。

避免错误

语法是关于语言的结构和正确性，没有什么比对你的文件进行快速校对更能达到这个目的了。让你的著作摆脱拼写错误、语法问题和语义上的不完善是非常重要的。

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

但是，如果你正在寻找一个一站式的语法工具，Grammarly是最广泛使用的工具之一。我并没有因此得到回扣或什么。它只是一个真正伟大的工具，许多编辑和作家使用它来写出干净和清晰的内容--类似于你可能使用Emmet、eslint或任何其他linter来写出干净和清晰的代码。

编写代码注释

我们为其他开发者写的东西会对我们工作的整体质量产生很大的影响，不管是我们在代码中写了什么，我们如何解释代码，或者我们如何对一段代码进行反馈。

有趣的是，每一种编程语言都有一套标准的功能来写注释。他们应该解释代码在做什么。我指的不是像这样模糊的注释。

red*= 1.2 // 将`red`乘以1.2，然后重新赋值

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

red*= 1.2 // 对图像施加 "偏红 "的效果。

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

评论应该增加价值

在我们研究什么是 "好的 "代码注释之前，这里有两个懒惰注释的例子。

constage= 32 // 初始化`年龄`为32

filter: blur(32px); /* 创建一个半径为32px的模糊效果 */

记住，注释的目的是为一段代码增加价值，而不是重复它。如果你不能做到这一点，你最好还是保持代码的原样。这些例子之所以 "懒惰"，是因为它们只是重述了代码明显在做的事情。在这种情况下，注释是多余的，因为它们告诉了我们已经知道的东西--它们并没有增加价值

评论应该反映当前代码的情况

过时的注释在大型项目中并不罕见；我敢说在大多数项目中也是如此。

让我们想象一下大卫，一个程序员，一个全能的人，可以和他一起玩。大卫想把一个字符串列表按字母顺序从A到Z排序，所以他在JavaScript中做了明显的动作。

cities= sortWords(cities) // 将城市从A到Z排序

然后大卫意识到sortWords()实际上是将列表从Z排序到A。这不是一个问题，因为他可以简单地扭转输出。

cities= sortWords(cities) // 将城市从A到Z排序cities= reverse(cities)

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

现在想象一下，我没有告诉你这个故事，而你看到的只是上面的代码。你自然会认为，在运行第二行代码后，`城市'会从Z到A排序！这是不可能的。这整个混乱的惨败是由一个陈旧的注释引起的。

虽然这可能是一个夸张的例子，但如果你在与最后期限赛跑时，类似的事情可能（而且经常）发生。值得庆幸的是，这可以通过遵循一个简单的规则来避免......在你改变代码的同时，改变你的注释。

这是一条简单的规则，它将使你和你的团队免于大量的技术债务。

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

评论应该解释不规范的代码

有时，自然的做事方式并不正确。程序员可能不得不 "破坏 "一下标准，但当他们这样做时，最好留下一个小评论，解释他们的理由。

 函数 addSetEntry(set,value) {/* 不要返回`set.add`，因为它在IE 11中不能被连锁。*/ set.add(value)。返回 set。}

这很有帮助，对吗？如果你负责审查这段代码，如果没有那条注释在那里解释是怎么回事，你可能会被诱惑去纠正它。

注释可以确定未来的任务

评论的另一个有用的东西是承认还有更多的工作要做。

// TODO: 使用一个更有效的算法linearSort(ids)

这样一来，你就可以专注于你的流程。而在以后，你（或其他人）可以回来修复它。

评论可以链接到源代码

所以，你刚刚在StackOverflow上找到了一个解决问题的方法。在复制粘贴这些代码后，保留一个帮助你的答案的链接有时是件好事，这样你就可以回来参考了。

// 增加了对传统浏览器的处理// https://stackoverflow.com/a/XXXXXXX

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

撰写拉动请求

拉动请求（PR）是任何项目的一个基本方面。它们是代码审查的核心。如果没有好的措辞，代码审查会很快成为你的团队业绩的一个瓶颈。

一个好的PR描述总结了正在进行的改变和为什么要这样做。大型项目都有一个拉动请求的模板，比如这个改编自真实案例的模板。

## 建议的修改在这里描述一下你的改动的大体情况，以便向维护者说明为什么我们应该接受这个拉动请求。## 更改的类型你的代码会给Appium带来哪些类型的变化？- [] 漏洞修复（修复问题的非破坏性改变）。- [] 新特性（增加功能的非破坏性改变）。- ...## 检查表- [] 我已经阅读了贡献文件- [] 我已经签署了CLA- [] 我的修改在本地通过了Lint和单元测试## 进一步的评论如果这是一个比较大的或复杂的修改，请在讨论时解释你为什么选择你所做的解决方案，以及你考虑了哪些替代方案，等等。

避免模糊的PR标题

请避免像这样的标题。

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

这些标题甚至没有试图描述我们正在处理的是什么构建、错误或补丁。多说一点细节，说明修复了构建中的哪一部分，消除了哪一个错误，或者增加了哪一个补丁，对与你的同事建立更好的沟通和协作有很大帮助。它能使人们处于同一水平线上。

公关标题传统上是用命令式写的。它们是整个公关的单行总结，它们应该描述公关正在做什么。

避免冗长的PR

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

相反，你可以。

• 通过问题与你的团队沟通。
• 制定一个计划。
• 将问题分解成小块，或者
• 在每一块上都有自己的PR。

现在是不是干净多了？

在PR正文中提供细节

与公关标题不同，正文是所有细节的地方，包括。

• 为什么要做这个公关？
• 为什么这是最好的方法？
• 该方法的任何缺点，以及解决这些缺点的想法（如果可能的话
• 错误或票据编号，基准结果，等等。

报告bug

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

对于技术项目，所有这些东西都是通过报告问题来完成的。一个写得很好的问题很容易让另一个开发者发现和回应。

例如，大多数大项目都有一个模板。

 <！--从angular-translate/angular-translate修改而来-->。

收集屏幕截图

使用你的系统的截屏工具捕捉问题。

如果是CLI程序的屏幕截图，确保文字清晰。如果是一个用户界面程序，确保屏幕截图捕捉到正确的元素和状态。

你可能需要捕捉一个实际的互动来证明这个问题。如果是这种情况，试着用屏幕录制工具录制GIF。

如何重现该问题

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

这里有一个例子。

更新：你实际上可以用对象重现这个错误。``html<div*ngFor="let value of objs; let i = index"><输入[ngModel]="objs[i].v" (ngModelChange)="setObj（i，$event）" /></div> 

建议一个原因

你是发现这个bug的人，所以也许你可以提出一些潜在的原因来说明为什么会出现这个bug。也许这个错误只在你遇到某个事件后发生，或者只在手机上发生。

探索代码库也没有什么坏处，也许可以找出导致问题的原因。然后，你的问题会更快地被关闭，你很可能被分配到相关的PR。

与客户沟通

你可能是一个单独的自由职业者，或者你是一个小团队的首席开发者。无论哪种情况，假设你负责在一个项目中与客户打交道。

现在，程序员的刻板印象是，我们的沟通能力很差。我们已经知道使用过度的技术术语，告诉别人什么是可能的，什么是不可能的，甚至当有人质疑我们的方法时，我们会采取防御措施。

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

提出正确的问题

首先要确保你和客户的想法是一致的。

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

提问也是一种积极写作的好方法，特别是在你不同意客户的反馈或决定的情况下。提出问题迫使那个人支持他们自己的主张，而不是你通过捍卫自己的立场来攻击他们。

• 即使有额外的性能成本，你可以接受吗？
• 移动这个部件是否有助于我们更好地实现我们的目标？
• 很好，发射后谁负责维护？
• 你知道这两种颜色的对比是否通过WCAG AA标准吗？

问题是更纯洁的，并且促进好奇心而不是敌意。

推销自己

如果你要向潜在的客户进行推销，你需要说服他们雇用你。客户为什么要选择你？明确以下几点很重要。

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

一旦你得到了这份工作，需要写一份合同，请记住，没有什么内容比一堆法律条文更令人畏惧。即使它是为设计项目而写的，合同杀手也可以成为一个很好的起点，来写一些更友好的东西。

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

撰写微文案

微文案是编写用户友好的用户界面信息的艺术，例如错误。我敢打赌，作为一个开发者，你曾有过不得不写错误信息的时候，因为它们一直被放在后面，直到启动时间。

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

错误。未预期的输入（代码693）。

错误是你最不想让你的用户面对的事情。但它们确实发生了，而我们对此却无能为力。这里有一些提示，以提高你的微文案技能。

避免使用技术术语

大多数人不知道服务器是什么，而100%的程序员知道。这就是为什么在错误信息中看到不常见的术语，如API或 "超时执行"，是很平常的事。

除非你面对的是一个技术客户或用户群，否则你的大多数用户很可能没有上过计算机科学课程，不知道互联网是如何工作的，也不知道为什么某个特定的东西不能工作。因此，出现了错误。

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

不要责怪用户

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

尽管认为这条信息有敌意似乎很有戏剧性，但它在潜意识里让我觉得很愚蠢。微文案说，责备用户是绝对不行的。试着把你的信息改成不那么指手画脚的东西，比如这个改自Mailchimp的登录的例子。"对不起，电子邮件和密码的组合不对。我们可以帮助你恢复你的账户。"

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

不要让用户不知所措

在你的微文案中使用幽默是一个好主意!它可以使气氛变得轻松，而且它是一种简单的方法，可以抑制由最糟糕的错误引起的消极情绪。

但是，如果你不完美地使用它，它可能会被认为是对用户的居高临下和侮辱。这只是一个很大的风险。

Mailchimp说得好。

[D]不要不顾一切地去开玩笑 - 强制的幽默可能比没有幽默更糟糕。如果你不确定，请保持正直的脸

。 (强调是我的)

编写无障碍标记

我们可以轻松地花一整篇文章来讨论无障碍性以及它与技术写作的关系。糟糕的是，无障碍性经常被包含在内容风格指南中，包括微软和Mailchimp的指南。

你是一个开发者，可能已经知道了很多关于无障碍性的知识。你甚至可能是一个比较勤奋的开发者，使无障碍性成为你工作流程的核心部分。然而，令人难以置信的是，无障碍性的考虑常常被放在后面，不管我们都知道使无障碍的在线体验包容所有能力是多么重要。

所以，如果你发现自己在代码中实施了别人的文案，为其他开发者写文档，甚至自己写UI文案，请注意一些基本的可及性最佳实践，因为它们完善了所有其他技术写作的建议。

诸如。

• 尽可能地使用语义标签（例如：<导航>、<标题>、<文章>，等等）
• 遵循合理的标题结构
• 为图片添加alt文本
• 注意内联语义（Mandy Michael有一篇关于这方面的特殊文章）

安迪-贝尔提供了一些你可以做的相对较小的事情，以使内容更容易被访问，这值得你花时间去看看。而且，为了好玩， 约翰-雷亚（John Rhea）展示了一些整洁的编辑技巧，当我们使用语义HTML元素时，这些 技巧是可能的。

总结

这是展示技术写作和开发如何重合的六种方式。虽然这些例子和建议可能不是火箭科学，但我希望你能发现它们是有用的，无论是与其他开发人员合作、维护自己的工作、在紧要关头不得不写自己的文案，甚至是起草项目建议书等等。

底线是：磨练你的写作技巧，在写作上多花点功夫，实际上可以使你成为一个更好的开发者。

技术写作资源

如果你对技术写作感兴趣。

• 技术写作的建议(Chris Coyier)
• 谷歌的技术写作指南
• 技术写作基础(GitLab)
• 用户体验写作。学习指南(Nielson Norman Group)
• 写文件（技术写作社区）

如果你对文案写作感兴趣。

• 文案写作101(Copyblogger)
• 什么是文案写作？(Ionos)
• SEO文案写作指南 (Semrush)
• 文案写作仍然是写作(The Guardian)

如果你对微文案感兴趣。

• 微文案简介(UX Planet)
• 苹果公司的人机界面指南
• 微软的写作风格指南
• Mailchimp的内容风格指南

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

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

如果你对写作的可及性感兴趣。

• 提高你网站内容的可读性(Andy Bell)
• 提高你的网站可访问性的15种做法(Bruce Lawson)
• 可访问性测试工具(Chris Coyier)
• 为什么开发者不认真对待无障碍性？(Melanie Sumner)
• 命名事物以提高可及性(Hidde de Vries)