/
index.md
177 lines (110 loc) · 10 KB
/
index.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
---
title: MDN Web 文档的收录标准
slug: MDN/Writing_guidelines/What_we_write/Criteria_for_inclusion
---
{{MDNSidebar}}
本文详细描述了 MDN Web 文档收录内容的标准，以及申请记录新的文档的流程，以及对申请方的期望和指南。
这是针对较大的项目的。如果要建议新增页面或文章，请参阅“MDN 收录规则”页面上的[建议内容](/zh-CN/docs/MDN/Writing_guidelines/What_we_write#内容建议)部分。
## Web 标准技术
MDN Web 文档的使命是记录由可靠的标准机构发布的规范中的 Web 标准技术，并且这些技术至少在一个稳定版本的浏览器中得到支持。这些标准表明了整个 Web 行业的兴趣、稳定性保证和“实现意愿”。因此，我们认为这些技术是我们花费时间和精力记录的安全选择。任何早于此阶段的 Web 技术或特性都可能因缺乏兴趣而被取消，或者可能非常不稳定，以致于可能会发生重大变化，这将不必要地涉及大量内容的重写（我们尽可能避免这种情况）。
## 非 Web 标准技术
非 Web 标准技术是指不符合上述标准的技术。我们通常不会考虑将其收录到 MDN Web 文档中。
我们的使命是“_为开放 Web 上的开发者提供他们所需的信息，以便轻松构建项目_”。这表明，我们应该考虑记录对 Web 开发者有用的技术，即使它们不是开放 Web 标准、标准轨道上的技术，等等。
如果你想考虑将非 Web 标准技术收录到 MDN Web 文档中，你应该确保它符合以下标准。
## MDN Web 文档的收录标准
技术应满足以下标准，才能被视为适合收录到 MDN Web 文档中。
### 开放且非专有
在 MDN Web 文档，我们支持开放技术。我们不支持由单一实体控制、不对任何利益相关方提供贡献机会、不能跨平台和系统进行互操作的封闭的技术生态系统。我们相信，开放创造的技术更有益于每个人。
### 与 Web 或 Web 技术相关
我们的核心职责是 Web 标准技术；记录与 Web 或 Web 技术无关，或者对 Web 开发者没有任何兴趣的技术是没有意义的。
### 存在兴趣和被采纳的迹象
我们不想花时间记录一个行业不感兴趣且未被采纳的技术。可能只是因为从现在就开始记录这项技术还为时过早，我们可以考虑在未来将其记录到 MDN Web 文档中。
### 没有显示出被弃用或被取代的迹象
与上述观点相关的是，我们也不想花时间记录已经处于生命周期的后期，并且已经显示出兴趣衰减迹象的技术。
### 在其他地方没有已建立的文档资源
现有许多库和框架，它们不是 Web 标准，但是建立在 Web 技术之上，并且在 Web 行业中非常流行。我们不会记录其中的任何一个，因为一般来说，它们都已经建立了文档资源。与流行框架的官方资源竞争是愚蠢的——这样做会浪费时间，而且可能会让试图学习该技术的开发者感到困惑。
### 有愿意为之编写和维护文档的社区
MDN Web 文档团队专注于记录开放 Web 平台。如果你想让 MDN Web 文档考虑记录某项技术，你需要组建一个愿意编写文档并在完成后维护文档的社区。我们团队很乐意在这种情况下提供包括编辑和反馈在内的指导，但我们没有除此以外的更多资源。
> **备注：** MDN Web 文档的工作是在 GitHub 上“公开”进行的。你的团队应该熟悉 git 和 GitHub，并且习惯于在开源项目中工作。
## 选择新技术的流程
如果一项技术看起来很适合在 MDN Web 文档上记录，你可以在 [GitHub 社区讨论](/zh-CN/docs/MDN/Community/Communication_channels#github_讨论)上发起讨论，以提议并讨论是否将该技术收录到 MDN Web 文档中。本节描述了该提议应包含的内容。
### 提交提议
要根据具体情况考虑是否将技术收录到 MDN Web 文档中。你需要提交一个标题为“Proposal for documenting a new technology on MDN Web Docs”（在 MDN Web 文档上记录新技术的提议）的提议，以供审议。我们需要你提供以下信息：
- 技术及其核心目的/用例和目标开发者受众。
- 对该技术最感兴趣的行业或社区有哪些？
- 有很多 Web 开发者在使用它吗？行业采用情况如何？
- 有很多 Web 开发者想要或需要这些信息吗？
- 这些信息的目标受众规模如何？如果有支持的统计数据，那么请提供。
- 该技术与核心 Web 技术和 Web 浏览器有何关联？有用的细节包括：
- 它是否使用 HTML 和 CSS，但通常不输出到 Web？
- Web 浏览器是否需要通过 polyfill 来支持它？
- 已有哪些文档或资源涵盖了该技术？
- 需要向 MDN Web 文档添加多少文档？
- 列出元素/方法/属性等的指南、教程、参考页面的预期数量。
- 提供高级目录。
- 除了基本文档页面之外，提及你认为可能需要的“高级”特性。你是否希望包含嵌入视频、交互式代码示例等？
- 编写文档的人员？他们是谁，以及为什么他们适合这份工作？
- 文档的维护方式是什么？
在这个阶段，你不需要向我们提供数百页的详细信息（事实上，我们更希望你不要这样做）。对于上述的每一点，用几段话就足够了。
> **备注：** MDN Web 文档主要是英文站点（en-US）。你的项目的主要语言应该是美式英语。
### 等待回复
我们将考虑你在提议中提交的技术和信息，并给出以下回复之一：
- **不予采纳**：我们认为这不符合 MDN Web 文档的收录标准。
- **可能采纳**：我们不确定它是否适合在 MDN Web 文档上记录，并且想要进一步提问。
- **采纳**：我们认为它适合在 MDN Web 文档上记录。
如果该技术是一个很好的候选项，团队将协助你开始编写文档。
## 记录新技术的项目指南
如果 MDN Web 文档接受了你选择的技术，那么下一步就是开始编写文档。
为确保你在 MDN Web 文档上记录新技术的项目取得成功，我们需要你做好以下准备：
- 专门的团队
- 项目计划和路线图
- 编写指南和标准
- 直观的文档结构
- 维护计划
### 专门的团队
确保你有一个专门的团队来编写初始文档，并在未来进行必要的更新。
考虑有多少工作量，以及可能需要多少人来完成。
- 如果这是一个大型项目，你可能需要一个由几位作者、一位检查工作是否在技术上准确的技术审阅者、一位清理内容的文字编辑、几位编写代码示例的人员等组成的团队，你会从中受益。
- 如果是一个小项目，你可能会有一两个人承担多个角色。只要对你有用，你想如何建立团队都可以。
MDN Web 文档团队中的成员将被分配到你的项目中，以提供来自 MDN Web 文档团队的指导。
你应该指定一名（或两名）团队负责人，他们可以与 MDN Web 文档团队成员联络。
MDN Web 文档的代表将帮助你的团队中的每个人获得在 [GitHub MDN 组织](https://github.com/mdn)中工作所需的权限。
### 项目计划和路线图
创建一个项目计划——任务、预计完成日期和里程碑，以确保你在稳步推进。
如果是项目很大，你应该考虑指定一个团队成员作为项目经理。你还应该考虑编写子项目计划，以发布最小可发布文档集合（_最小可行产品_）；之后可以进行进一步的添加。
如果文档记录项目很小，你仍然需要记录已完成和未完成的工作，文档记录的每一部分处于什么阶段（例如，未开始、进行中、已撰写草稿、已审核、已完成），以及谁在做什么工作。
### 编写指南和标准
这些[指南](/zh-CN/docs/MDN/Writing_guidelines)说明了我们期望如何为 MDN Web 文档编写文档。
如果你对正在编写的文档有其他指南，我们希望将其添加到本指南中，并确保其内容是最新的。
就标准而言，我们期望你保证合理的写作质量，以便你的文档能够保留在 MDN Web 文档上。MDN Web 文档的代表将与你合作，让你明确知道期望的内容。
### 直观的文档结构
如果你已经通过了提议提交流程，那么你应该已经有了一个粗略的大纲，知道你将为这项技术编写的内容。此时，你应该将其细化为站点结构计划：考虑文档层次结构将是什么样子，以及所有内容如何组织和链接在一起。
每个项目不尽相同，但我们大致建议如下：
```plain
着陆页
|
------参考
|
--------元素
|
--------方法
|
--------其他参考页类型？
|
------指南/教程
|
------示例
```
每个项目中使用的每个页面类型都应该有一个页面模板，供其他人从中复制结构。你应该尽早决定这些。
请参阅我们关于[页面类型](/zh-CN/docs/MDN/Writing_guidelines/Page_structures/Page_types)的部分。如果需要添加，请与你的 MDN Web 文档代表联系。
### 维护计划
该技术的文档需要维护，以将其保留在 MDN Web 文档上：
- MDN Web 文档的内容和文件存储在 GitHub 上。当其他人对你的技术文档进行更改时，你的团队成员需要审查这些更改，以确保内容仍然良好。你可以通过 GitHub 的通知功能跟踪打开的拉取请求（PR）。
- 当技术发生变化需要更新文档时，你的团队需要在保持与原始文档相同的标准的情况下，对文档进行适当的更新。
如果在六个月的时间内没有观察到积极的变化，并且文档似乎处于以下任何状态：
- 陈旧或无人维护
- 在没有完成的情况下停滞不前
- 质量低下
- 逐渐过时
那么我们将认为该技术的文档已死。在经过 MDN Web 文档团队代表与你的团队的讨论后，文档将被删除。
我们希望你能理解，我们需要严格对待这些问题——我们不能让网站充斥着质量低下、不完整或过时的文档。