mirror of
https://github.com/goldbergyoni/nodebestpractices.git
synced 2025-10-29 00:19:14 +08:00
improve writing-guidelines.chinese.md
This commit is contained in:
@ -1,31 +1,31 @@
|
||||
# 我们的内容写作声明
|
||||
如何提高访问者的阅读和学习体验
|
||||
# 我们创作内容的准则
|
||||
|
||||
提高访问者的阅读和学习体验
|
||||
|
||||
## 1. 越简单越好
|
||||
|
||||
<br/>
|
||||
我们的使命, 我们管理内容是为了使阅读和吸收知识更容易。因此, 我们专注于将复杂和无趣的话题转化为一个简化的清单, 用缩短和不那么精确的细节来交易超载信息, 避免 ‘易燃’ 和有争议的话题, 摆脱主观想法, 赞成普遍接受做法
|
||||
我们的使命,是使知识更易于理解与吸收。因此,我们专注于将复杂和无趣的话题转化为一个简化的清单,用简短但细节相对不精确的列表,去避免超负荷的信息量。同时避免涉及”易爆炸“和有争议的话题。摆脱主观观点,赞成普遍接受的实践。
|
||||
|
||||
<br/>
|
||||
## 2. 基于证据且可靠
|
||||
|
||||
## 2. 以证据为基础并且可靠
|
||||
我们应使得我们的内容能让读者充分信任其可靠性。为实现这一点,我们加入引用、数据和与主题相关的其他资源。实践上,通过努力包括来自可靠来源的引用话语,展示基准测试结果、相关的设计模式,或采用任何其他的科学手段以证明您的主张。
|
||||
|
||||
<br/>
|
||||
我们的读者应该有很大的信心, 他们浏览的内容是可靠的。我们通过包括引用、数据和本主题可用的其他资源等证据来实现这一点。实际上, 努力包括可靠来源的引用, 显示基准, 相关的设计模式或任何科学措施, 以证明您的主张
|
||||
## 3. MECE(不重不漏)
|
||||
|
||||
|
||||
## 3. MECE (Mutually Exclusive and Collectively Exhaustive)
|
||||
除了大量编辑和可靠的内容, 通过它略读也应该提供全面覆盖的主题。不应排除重要的子主题
|
||||
除了要精心编写和可靠,一个话题应该做到略读它之后能涉及到该话题的全部知识。任何重要的子话题都不能遗漏。
|
||||
|
||||
## 4. 一致的格式
|
||||
内容是使用固定模板显示的。任何将来的内容都必须符合同一模板。如果希望添加新项目符号, 请从现有项目符号复制项目符号格式, 并将其扩展以满足您的需要。有关其他信息, 请查看[模版](https://github.com/goldbergyoni/nodebestpractices/blob/master/sections/template.md)
|
||||
|
||||
## 5. 关于Node.js
|
||||
每个建议都应直接与Node.js相关, 而不是一般软件开发。当我们建议在Node.js中实现通用模式/规则时, 内容应该集中在Node的实现上。例如, 当我们建议将所有请求的输入为了安全原因进行处理时, 应使用Node行话 - '使用中间件来处理请求输入'
|
||||
内容是使用固定模板显示的。任何新的内容都必须遵守这一模板。如果希望添加新项目符号,请从现有项目符号复制项目符号格式,并将其扩展以满足您的需要。有关其他信息,请查看[模版](https://github.com/goldbergyoni/nodebestpractices/blob/master/sections/template.md)
|
||||
|
||||
## 6. 仅限主要的vendor
|
||||
有时, 包括可以解决某些挑战和问题 (如 npm 软件包、开源工具甚至商业产品) 的供应商名称是很有用的。为了避免极长的列表或推荐信誉不好和不稳定的项目, 我们提出了以下规则:
|
||||
## 5. Node.js 相关
|
||||
|
||||
- 只有排名前3的vendor应该被推荐 – 对于一个给定的相关关键词,如果某个vendor出现在搜索引擎结果中排名前3(谷歌或GitHub通过人气排序),那么它可以包含在我们的推荐里
|
||||
- 如果它是一个npm包,它必须平均一天下载至少750次
|
||||
- 如果它是一个开源项目,它必须在过去的6个月里至少更新一次
|
||||
每个建议都应直接与 Node.js 相关,而不能仅仅是一般的软件开发。当我们建议在 Node.js 中实现通用的模式/规则时,内容应该集中在 Node 的实现上。例如,当我们建议将所有请求的输入为了安全原因进行处理时,应使用 Node 行话——‘使用中间件来处理请求输入’,如果一个条目在 Node.js 中没有具体特别的实现(e.g. 在 Python 或 Java 中看起来一样)——则将其包含在一个通用的容器条目,例子请查看条目 6.5。
|
||||
|
||||
## 6. 仅限主要的厂商
|
||||
|
||||
有时, 为解决某些问题和挑战,可以包含一些软件 (如 npm 软件包、开源工具甚至商业产品) 的厂商名。为了避免极长的列表,或推荐信誉不好或不稳定的项目,我们提出了以下规则:
|
||||
|
||||
- 只有排名前 3 的厂商应该被推荐 – 对于一个给定的相关关键词,如果某个厂商出现在搜索引擎结果中排名前3(谷歌或 GitHub 通过人气排序),那么它可以包含在我们的推荐里。
|
||||
- 如果它是一个 npm 包,平均日下载量应至少 750 次。
|
||||
- 如果它是一个开源项目,在过去的 6 个月里必须至少更新过一次。
|
||||
|
||||
Reference in New Issue
Block a user