如何写一个好的说明文件 #8665

Ashira97 · 2021-05-24T01:02:02Z

译文翻译完成，resolve #8592

同步

同步更新

update1

11

完成

kimberlyohq · 2021-05-24T05:00:30Z

@lsvih 校对认领

kimberlyohq

@lsvih 校对完毕

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

kimberlyohq · 2021-05-24T05:10:39Z

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


-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)为网络规范提供了一个良好的入门说明。


Suggested change

[这一由 W3C TAG 颁布的向导](https://github.com/w3ctag/w3ctag.github.io/blob/master/explainers.md)为网络规范提供了一个良好的入门说明。

这篇由 W3C TAG 发布的[指南](https://github.com/w3ctag/w3ctag.github.io/blob/master/explainers.md)对网络规范有很好的介绍。

这篇由 W3C TAG 发布的指南对网络规范有很好的介绍。
-> 这篇由 W3C TAG 发布的指南对网页规范有很好的介绍。

这里的 web specifications 翻译为网页规范似乎更合理

建议这一行内容和上一行合并一下，毕竟原文就是在一行中的，和原文保持一致

好的这里是我翻译的时候没有注意到同一行的问题感谢斧正~

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

lsvih · 2021-05-24T06:22:49Z

@kimberlyohq 感谢校对

KimYangOfCat · 2021-05-24T09:07:42Z

@lsvih 认领校对

lsvih · 2021-05-24T10:28:37Z

@KimYangOfCat 欢迎校对

KimYangOfCat

校对了一部分，没有校对完

KimYangOfCat · 2021-05-25T13:00:22Z

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


-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)为网络规范提供了一个良好的入门说明。


这篇由 W3C TAG 发布的指南对网络规范有很好的介绍。
-> 这篇由 W3C TAG 发布的指南对网页规范有很好的介绍。

这里的 web specifications 翻译为网页规范似乎更合理

建议这一行内容和上一行合并一下，毕竟原文就是在一行中的，和原文保持一致

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

KimYangOfCat · 2021-05-25T13:18:58Z

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

 > * 校对者：

-# How to write a good explainer
+# 如何写一个好的解释文件


Suggested change

# 如何写一个好的解释文件

# 如何写一个好的说明文件

关于 explainer 的翻译，我认为意译为说明文件，相比于现在直译为解释文件，阅读体验更好，意思感觉也更准确。
如果你采纳这个校对意见的话，就请全文修改一下，保证所有 explainer 的翻译统一

欢迎另一位校对者参与讨论。

好的已经修改~

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

KimYangOfCat · 2021-05-25T14:13:45Z

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


-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 文件中， 本文为您提供了一系列可选择的建议。


Suggested change

并不是所有的部分都需要包含在 README.md 文件中，本文为您提供了一系列可选择的建议。

并非模板中的所有章节都需要被引入，这些只是一系列可选择的建议。

和前文有些重复，所以删减一些

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

KimYangOfCat

@lsvih 校对完毕
@Ashira97 有一说一，本文的翻译质量不是很好，出现了以下问题：

全文翻译不统一，前后出现多个翻译版本
个别句子理解错误，导致原文与译文所表达的意思天差地别，这是很多刚尝试意译的同学常出现的问题，建议在尝试意译之前，确保直译准确，再尝试使用意译。
格式问题，目前你是一句一行的形式进行的翻译，我个人非常不推荐这种方式，虽然不影响最终的 markdown 渲染，但是挺影响源码的阅读体验的。所以最好和原文保持一致，段落分明更好。

希望你接受以上问题并改正，加油嗷～
最后给你个小建议，自己翻译完之后，自己拿着译文阅读一遍，如果你自己能理解译文的内容，那就可以 commit 了，但是如果不能的话，请再多修改一下，这样才能提升自己的翻译水平嗷。

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

KimYangOfCat · 2021-05-25T15:24:33Z

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

 - [JSC]()
 - [SpiderMonkey]()
 - ...

-## Q&A
+## 问题及回答


Suggested change

## 问题及回答

## 常见问题

感觉似乎不翻译也行，应该没人不知道 Q&A 的意思吧？（哈哈

哈哈确实

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

校对修改完成

Ashira97 · 2021-05-26T02:34:15Z

@lsvih 校对完成
@kimberlyohq @KimYangOfCat 感谢两位老师校对谢谢提出的建议~ 我下次改进 ~

KimYangOfCat · 2021-05-26T02:56:01Z

article/ECMA-TC39/How-to-write-a-good-explainer.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 提案说明的建议，以及可能想在您的提案说明文件中引用的内容大纲。


这里原文也只有一行嗷，将你的两行合并一下吧

KimYangOfCat · 2021-05-26T02:56:20Z

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


-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 文件中的模板。


这里原文也只有一行嗷，将你的三行合并一下吧

已修改谢谢~

kimberlyohq · 2021-05-26T03:26:52Z

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


 ----

-# Frobnicator
+# 制作者


@KimYangOfCat @Ashira97

Frobnicator 翻译成制作者我觉得有点不太正确？

The word “frobnicate” in IT is a kind of techie slang that describes tweaking or fiddling with physical parts of a technology.

制作者 -> 修改/调整者? 大家怎么看

这个词上下文的语境不是很强，所以确实蛮难翻译的，这里应该指的不是一类人，感觉 调整者 也不是很准确，
原文这个词出现了两次，另一次是在第 97 行，那里将其译作了 装配模块。

Additionally, web browsers already have a built-in frobnicator which is higher quality.

我查了一下但也没有查到太多实用的信息，如果实在拿不准，我倾向于不翻译。抱歉根据我目前了解到的的信息，我也不知道怎么翻译，

那我先按照装配器/装配模块翻译，在中文翻译后做个备注吧~ 这样也方便读者直接用英文关键词查找~

PassionPenguin

凑个热闹

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

Ashira97 · 2021-05-27T05:44:31Z

@kimberlyohq @KimYangOfCat @PassionPenguin 已修改谢谢三位老师的建议大家看看还有什么要改的地方吗~

Ashira97 added 6 commits February 13, 2021 13:45

Merge pull request #1 from xitu/master

a3e7711

同步

Merge pull request #2 from xitu/master

67df8ef

同步更新

Merge pull request #3 from xitu/master

09481b7

同步更新

update1

cc4dfcb

update1

Update How-to-write-a-good-explainer.md

bae18b5

11

Update How-to-write-a-good-explainer.md

839d545

完成

lsvih changed the title ~~Translation/how to write a good explainer~~ 如何写一个好的解释文件Translation/how to write a good explainer May 24, 2021

lsvih changed the title ~~如何写一个好的解释文件Translation/how to write a good explainer~~ 如何写一个好的解释文件 May 24, 2021

lsvih added ECMA-TC39 前端校对认领 labels May 24, 2021

kimberlyohq reviewed May 24, 2021

View reviewed changes

lsvih added the 正在校对 label May 24, 2021

lsvih removed the 校对认领 label May 24, 2021

KimYangOfCat reviewed May 25, 2021

View reviewed changes

article/ECMA-TC39/How-to-write-a-good-explainer.md Outdated Show resolved Hide resolved

Update How-to-write-a-good-explainer.md

7748085

校对修改完成

KimYangOfCat reviewed May 26, 2021

View reviewed changes

Update How-to-write-a-good-explainer.md

2ee2c5a

kimberlyohq reviewed May 26, 2021

View reviewed changes

PassionPenguin previously approved these changes May 26, 2021

View reviewed changes

Update How-to-write-a-good-explainer.md

34a3491

Ashira97 dismissed PassionPenguin’s stale review via 34a3491 May 27, 2021 05:39

Update How-to-write-a-good-explainer.md

0ee314c

lsvih approved these changes May 27, 2021

View reviewed changes

lsvih merged commit 350c1c9 into xitu:master May 27, 2021

lsvih added 翻译完成 and removed 正在校对 labels May 27, 2021

lsvih changed the title ~~如何写一个好的解释文件~~ 如何写一个好的说明文件 Oct 9, 2021

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

如何写一个好的说明文件 #8665

如何写一个好的说明文件 #8665

Ashira97 commented May 24, 2021

kimberlyohq commented May 24, 2021

kimberlyohq left a comment

kimberlyohq May 24, 2021

KimYangOfCat May 25, 2021

Ashira97 May 26, 2021

lsvih commented May 24, 2021

KimYangOfCat commented May 24, 2021

lsvih commented May 24, 2021

KimYangOfCat left a comment

KimYangOfCat May 25, 2021

KimYangOfCat May 25, 2021

kimberlyohq May 25, 2021

Ashira97 May 26, 2021

KimYangOfCat May 25, 2021

KimYangOfCat left a comment •

edited

Loading

KimYangOfCat May 25, 2021

Ashira97 May 26, 2021

Ashira97 commented May 26, 2021

KimYangOfCat May 26, 2021

KimYangOfCat May 26, 2021

Ashira97 May 26, 2021

kimberlyohq May 26, 2021

KimYangOfCat May 26, 2021 •

edited

Loading

Ashira97 May 27, 2021

PassionPenguin left a comment

Ashira97 commented May 27, 2021

	[这一由 W3C TAG 颁布的向导](https://github.com/w3ctag/w3ctag.github.io/blob/master/explainers.md)为网络规范提供了一个良好的入门说明。
	这篇由 W3C TAG 发布的[指南](https://github.com/w3ctag/w3ctag.github.io/blob/master/explainers.md)对网络规范有很好的介绍。

	# 如何写一个好的解释文件
	# 如何写一个好的说明文件

	并不是所有的部分都需要包含在 README.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 提案说明的建议，以及可能想在您的提案说明文件中引用的内容大纲。


		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 文件中的模板。

如何写一个好的说明文件 #8665

如何写一个好的说明文件 #8665

Conversation

Ashira97 commented May 24, 2021

kimberlyohq commented May 24, 2021

kimberlyohq left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lsvih commented May 24, 2021

KimYangOfCat commented May 24, 2021

lsvih commented May 24, 2021

KimYangOfCat left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KimYangOfCat left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ashira97 commented May 26, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

KimYangOfCat May 26, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PassionPenguin left a comment

Choose a reason for hiding this comment

Ashira97 commented May 27, 2021

KimYangOfCat left a comment •

edited

Loading

KimYangOfCat May 26, 2021 •

edited

Loading