如何写一个好的说明文件

article/ECMA-TC39/How-to-write-a-good-explainer.md

@@ -2,105 +2,111 @@
 > * 原文作者：[Ecma TC39](https://github.com/tc39/how-we-work)
 > * 译文出自：[掘金翻译计划](https://github.com/xitu/gold-miner)
 > * 本文永久链接：[https://github.com/xitu/gold-miner/blob/master/article/ECMA-TC39/How-to-write-a-good-explainer.md](https://github.com/xitu/gold-miner/blob/master/article/ECMA-TC39/How-to-write-a-good-explainer.md)
-> * 译者：
+> * 译者：[Ashira97](https://github.com/Ashira97)
 > * 校对者：
 
-# How to write a good explainer
+# 如何写一个好的解释文件
 
-Each TC39 proposal should have a README.md file which explains the purpose of the proposal and its shape at a high level. [This guide](https://github.com/w3ctag/w3ctag.github.io/blob/master/explainers.md) by the W3C TAG has a good introduction for web specifications
+每一个 TC39 提案都包括了 README.md 文件来说明该提案目的和高层的发展方向。
+[这一由 W3C TAG 颁布的向导](https://github.com/w3ctag/w3ctag.github.io/blob/master/explainers.md)为网络规范提供了一个良好的入门说明。
 
-This page you're on has some additional advice for how to write an explainer for TC39 proposals, with an outline for content that you might want to include in your proposal's explainer. For some well-written explainers in recent proposals, see [Promise.allSettled](https://github.com/tc39/proposal-promise-allSettled), the [Temporal proposal](https://github.com/tc39/proposal-temporal), or [RegExp Unicode property escapes](https://github.com/tc39/proposal-regexp-unicode-property-escapes).
+您正在浏览的页面提供了额外建议来帮助您书写一个用于 TC39 提案的解释器，该页面也包含了一个内容的纲要，您可能想要将该纲要包含到您的提案的解释器中。
+如果您想要浏览近期提案的书写完善的解释文件，看 [Promise.allSettled](https://github.com/tc39/proposal-promise-allSettled)，[Temporal proposal](https://github.com/tc39/proposal-temporal)，或者是 [RegExp Unicode property escapes](https://github.com/tc39/proposal-regexp-unicode-property-escapes)。
 
-The rest of this page can be used as a template, to put in your README.md. Not all sections need to be included: This is just a series of optional suggestions. In *italics* is the instructions, and in plain text is the example text. Most of what's here besides the headings should be replaced by your own content.
+本页接下来的内容可以作为您的 README.md 文件中的模板
+并不是所有的部分都需要包含在 README.md 文件中， 本文为您提供了一系列可选择的建议。
+在引导中的*斜体字样*和普通文本是样例文本。大多数在头部文章之后的内容都应该用您自己的内容代替。
 
 ----
 
-# Frobnicator
+# 制作者
 
-## Status
+## 状态
 
-Champion(s): *champion name(s)*
-Author(s): *non-champion author(s), if applicable*
-Stage: -1
+主要作者：*主要作者姓名*
+作者：*非主要作者姓名，如果有的话*
+阶段：-1
 
-## Motivation
+## 动机
 
-*Why is this important to have in the JavaScript language?*
+*为什么应该使用 JavaScript 编程语言？*
 
-Frobnication comes up in all areas of computer science, in both front-end and back-end programming. See [CATB](http://catb.org/jargon/html/F/frobnicate.html) for details.
+不断的修改和调整代码存在于计算机的所有领域中，无论是前端开发到后端开发。
+详细信息请看 [CATB](http://catb.org/jargon/html/F/frobnicate.html)。
 
-## Use cases
+## 用例
 
-*Some realistic scenarios using the feature, with both code and description of the problem; more than one can be helpful.*
+*列举出使用该特性的一些实际场景，可以列出代码和问题描述；当你这么做的时候，不仅仅是在这一种情况下可以有帮助。*
 
-**Server-side static frobnication**: Say you want to frobnicate a thing. Then, you would normally have to do all this stuff. If it's in the standard library, it'd be easier.
+**服务端静态装配**：加入你想要装配某个功能，那么你将要做所有的一系列工作。如果有标准的第三方库提供，这些事情就会容易很多。
 
 ```js
 frobnicate({});
 ```
 
-**Dynamic frobnicate cases**: The object is provided in a different way, and a different sort of use case comes up, which can be met by the same feature.
+**动态装配案例：**：对象以不同的方式提供，并且出现了不同类型的用例，这些用例可以由相同的特性实现。
 
-## Description
+## 描述
 
-*Developer-friendly documentation for how to use the feature*
+*一份对开发者友好的文档应该写明如何使用特性*
 
-`frobnicate(object)` returns the frobnication of object.
+`frobnicate(object)`返回了一个装配实例。
 
-## Comparison
+## 比较
 
-*A comparison across various related programming languages and/or libraries. If this is the first sort of language or library to do this thing, explain why that is the case. If this is a standard library feature, a comparison across the JavaScript ecosystem would be good; if it's a syntax feature, that might not be practical, and comparisons may be limited to other programming languages.*
+*横跨相关编程语言和类似的第三方库的比较。如果当前项目是该语言或者该第三方库第一次对某功能的实现，就请解释为什么该功能是应该实现的。如果这是一个标准库的特性，那么最好在 JavaScript 的生态中做横向比较；如果这是一个可能并不实用的语法特性，那么在不同编程语言之间的横向比较则可能会受限。*
 
-These npm modules do something like the proposal:
+npm 模块按照提案实现了以下功能：
 - [frobnicate-2018](https://www.npmjs.com/package/frobnicate-2018)
 - [B](link)
 - [C](link)
 
-frobnicate-2018 is weird because xyz, whereas B is weird because jkl, so we take a version of the approach in C, modified by qrs.
+frobnicate-2018 是一个奇怪的特性，因为...，然而 B 也是奇怪的因为...，所以我们采用了 C 中的方法，这一方法由 qrs 进行修改。
 
-The standard libraries of these programming languages includes related functionality:
-- APL (links to the relevant documentation for each of these)
+这些编程语言的标准库包含相关的功能：
+- APL (对于涉及到的每一项都应该有相关文档的链接)
 - PostScript
 - Self
 - XSLT
 - Emacs Lisp
 
-Our approach is pretty similar to the Emacs Lisp approach, and it's clear from a manual analysis of billions of Stack Overflow posts that this is the most straightforward to ordinary developers.
+我们的方法与 Emacs Lisp 方法非常相似，通过对数十亿篇 Stack Overflow 文章的手工分析可以清楚地看出，对于普通开发人员来说，这是最简单的方法。
 
-## Implementations
+## 实现
 
-### Polyfill/transpiler implementations
+### Polyfill/转译器的实现
 
-*A JavaScript implementation of the proposal, ideally packaged in a way that enables easy, realistic experimentation. See [implement.md](https://github.com/tc39/how-we-work/blob/master/implement.md) for details on creating useful prototype implementations.*
+*该提案中理想的 JavaScript 打包方式实现是简单、可行的。关于创建原型实现的详细信息，请参见 [implement.md](https://github.com/tc39/how-we-work/blob/master/implement.md)。*
 
-You can try out an implementation of this proposal in the npm package [frobnicate](https://www.npmjs.com/package/frobnicate). Note, this package has semver major version 0 and is subject to change.
+你可以使用 npm 包  [frobnicate](https://www.npmjs.com/package/frobnicate) 中尝试这个建议的实现。注意，这个包有 semver 主版本 0，可能会发生变化。
 
-### Native implementations
+### 简单实现
 
-*For Stage 3+ proposals, and occasionally earlier, it is helpful to link to the implementation status of full, end-to-end JavaScript engines. Filing these issues before Stage 3 is somewhat unnecessary, though, as it's not very actionable.*
+*对于阶段3以上或者更早的提案，将完全的、端到端的 javascript 引擎的实现状态链接到文中是非常有帮助的。然而在阶段 3 之前填充这些提议有些时候是多余或者非常不可行的。*
 
-- [V8]() (*Links to tracking issues in each JS engine*)
+- [V8]() (*提供在 JS 引擎中用于跟踪问题的链接*)
 - [JSC]()
 - [SpiderMonkey]()
 - ...
 
-## Q&A
+## 问题及回答
 
-*Frequently asked questions, or questions you think might be asked. Issues on the issue tracker or questions from past reviews can be a good source for these.*
+*常见问题，或者你认为可能会被问到的问题。问题跟踪器上的问题或过去评审中的问题可能是您编写这一部分的很好的参考。*
 
-**Q**: Why is the proposal this way?
+**问题**：为什么会出现这样的提议？
 
-**A**: Because reasons!
+**回答**：因为...
 
-**Q**: Why does this need to be built-in, instead of being implemented in JavaScript?
+**问题**：为什么他需要被内置实现而不是在 JavaScript 中实现？
 
-**A**: We could encourage people to continue doing this in user-space. However, that would significantly increase load time of web pages. Additionally, web browsers already have a built-in frobnicator which is higher quality.
+**回答**：我们一直鼓励用户在用户空间中做这件事。然而，这样会非常严重地增加页面的加载时间。不仅如此，web 浏览器已经有高质量的内置装配模块。
 
-**Q**: Is it really necessary to create such a high-level built-in construct, rather than using lower-level primitives?
+**问题**：真的有必要创建这样一个高级的内置装配模块而不是使用低级特性吗？
+
+**回答**：我们可以暴露更多的基础特性来组装 MD5 哈希模块和 ROT13 模块而不是提供一个直接的 `frobnicate` 方法。然而 rot13 在2012年被发现是不安全的，所以将它 作为一个基础特性暴露可能会导致相关的安全问题。
 
-**A**: Instead of providing a direct `frobnicate` method, we could expose more basic primitives to compose an md5 hash with rot13. However, rot13 was demonstrated to be insecure in 2012 (citation), so exposing it as a primitive could serve as a footgun.
 > 如果发现译文存在错误或其他需要改进的地方，欢迎到 [掘金翻译计划](https://github.com/xitu/gold-miner) 对译文进行修改并 PR，也可获得相应奖励积分。文章开头的 **本文永久链接** 即为本文在 GitHub 上的 MarkDown 链接。
 
 ---
 
-> [掘金翻译计划](https://github.com/xitu/gold-miner) 是一个翻译优质互联网技术文章的社区，文章来源为 [掘金](https://juejin.im) 上的英文分享文章。内容覆盖 [Android](https://github.com/xitu/gold-miner#android)、[iOS](https://github.com/xitu/gold-miner#ios)、[前端](https://github.com/xitu/gold-miner#前端)、[后端](https://github.com/xitu/gold-miner#后端)、[区块链](https://github.com/xitu/gold-miner#区块链)、[产品](https://github.com/xitu/gold-miner#产品)、[设计](https://github.com/xitu/gold-miner#设计)、[人工智能](https://github.com/xitu/gold-miner#人工智能)等领域，想要查看更多优质译文请持续关注 [掘金翻译计划](https://github.com/xitu/gold-miner)、[官方微博](http://weibo.com/juejinfanyi)、[知乎专栏](https://zhuanlan.zhihu.com/juejinfanyi)。
+> [掘金翻译计划](https://github.com/xitu/gold-miner) 是一个翻译优质互联网技术文章的社区，文章来源为 [掘金](https://juejin.im) 上的英文分享文章。内容覆盖 [Android](https://github.com/xitu/gold-miner#android)、[iOS](https://github.com/xitu/gold-miner#ios)、[前端](https://github.com/xitu/gold-miner#前端)、[后端](https://github.com/xitu/gold-miner#后端)、[区块链](https://github.com/xitu/gold-miner#区块链)、[产品](https://github.com/xitu/gold-miner#产品)、[设计](https://github.com/xitu/gold-miner#设计)、[人工智能](https://github.com/xitu/gold-miner#人工智能)等领域，想要查看更多优质译文请持续关注 [掘金翻译计划](https://github.com/xitu/gold-miner)、[官方微博](http://weibo.com/juejinfanyi)、[知乎专栏](https://zhuanlan.zhihu.com/juejinfanyi)。