如何在文档中编写、复习和指导更好的英语语言？
我的工作定期涉及在我们的内部系统文档中(以“拉请求”的形式)写作和复习英文散文，这是我们内部系统的唯一面临，在一家遍布世界各地的美国公司里。
这种写作分为两类--文档网站和API中的文档片段(例如，REST的Swagger文档)。我觉得这两者对用户对我们的系统/产品的最初印象有很大的影响，而最初的印象对我来说很重要。我们团队中没有正式的技术撰稿人，也没有我所知道的公司里的任何技术作家。
我是一个以英语为母语的人，我在学校里的英语学得还不错。我的团队中有一半以上不是以英语为母语的人。显然，他们的英语比我在其他语言方面的能力要好得多，他们的英语写作和说得很好。
然而，我经常对我在文档中看到的英语质量感到失望，包括来自以英语为母语的人。我非常乐意回顾代码--基于静态分析、最佳实践、团队指南、经验规则和个人经验。回顾文档的变化，我显然不那么自在--我不觉得我有基准点或具体的证据可依赖，只是我从学校开始就一直在使用的直觉。最后，我常常用我认为文本应该是什么来评论PRs，没有太多的理由或逻辑。
在糟糕的一天，这让我对自己的写作产生疑问。没有人会评论我的英语，所以我不会像我的代码那样得到定期的反馈。这也让我觉得，如果我不能确定我自己的写作，我不应该指导初级开发人员改进他们的。
我不确定我是否只是缺少编程语言和编译器的舒适度和安全性，或者这里是否有真正的改进空间。我怎样才能改进我写的东西，我对文档的建设性批评，最终改进整个团队？
回答 4
Software Engineering用户
发布于 2020-05-13 22:51:00
您可能已经找到了一些改进您的“程序员词汇表”的资源，使您更容易权威地讨论编程概念。例如，你可能已经对做得太多的课程有了一种直觉，然后你读到了关于单一责任原则的文章，它帮助你在脑海中重新定义了这个概念。
大多数其他创造性领域都有类似的资源。对于写作，像规范斯特兰克与怀特这样的样式指南填补了这个角色。它列出了关于写作的具体规则，你可能只有直觉。这将有助于提供你认为你一直在失踪的理由。
Software Engineering用户
发布于 2020-05-13 21:16:22
我感受到了你的痛苦，有时很难找到那些擅长编码和有良好写作技能的人(即使他们必须用他们的母语编写文档)。
提高一个人的写作技能需要很多年。因此，我所知道的平衡这一点的唯一方法是，尝试找到一个写得很好的人(不需要是一个程序员)，并明确地赋予他们定期检查文档的任务。也许你的组织里有一个人，也许你需要从外部雇佣一个人来完成这个任务。
(个人注意:每当有人纠正我在这里回答的错误时，我真的很高兴，因为你肯定注意到，我自己不是说英语的人，而且经常忽视以英语为母语的人一眼就能看到的打字或语法问题。)
Software Engineering用户
发布于 2020-05-13 21:17:58
没有人评论我的英语，所以我没有得到定期的反馈
这是你的问题。没有一个地方的英语说得足够好，他们不需要反馈。
找一个人，任何人，让他们检查你写的东西。注意他们对这件事的看法和理解程度。
别等这个。伸出手寻求帮助。经常这么做。别把20页纸丢到我桌上要便条。让我成为你写作过程中的一部分。别只问我。问其他人也一样。
这样做，人们很快就会意识到你想要反馈，并将更愿意提供它。
https://softwareengineering.stackexchange.com/questions/410099
复制相似问题
腾讯云开发者
