From 310fd066e91f454b990372ffa30e803cc8120975 Mon Sep 17 00:00:00 2001 From: Florian Merz Date: Thu, 11 Feb 2021 12:56:40 +0100 Subject: unslug zh-cn: move --- files/zh-cn/mdn/at_ten/index.html | 37 + files/zh-cn/mdn/community/conversations/index.html | 59 -- files/zh-cn/mdn/community/doc_sprints/index.html | 123 ---- files/zh-cn/mdn/community/index.html | 53 -- .../zh-cn/mdn/community/whats_happening/index.html | 42 -- .../index.html" | 101 --- .../index.html | 30 + .../index.html | 185 +++++ .../howto/create_an_mdn_account/index.html | 44 -- .../howto/do_a_technical_review/index.html | 57 -- .../howto/do_an_editorial_review/index.html | 55 -- .../howto/set_the_summary_for_a_page/index.html | 59 -- .../howto/tag_javascript_pages/index.html | 69 -- .../index.html | 117 --- .../index.html" | 30 - .../index.html" | 185 ----- .../index.html" | 53 -- files/zh-cn/mdn/editor/basics/index.html | 61 -- .../mdn/editor/basics/page_controls/index.html | 37 - files/zh-cn/mdn/editor/basics/page_info/index.html | 47 -- files/zh-cn/mdn/editor/edit_box/index.html | 145 ---- files/zh-cn/mdn/editor/index.html | 20 - files/zh-cn/mdn/editor/source_mode/index.html | 121 ---- .../zh-cn/mdn/guidelines/content_blocks/index.html | 45 -- .../guidelines/does_this_belong_on_mdn/index.html | 193 +++++ .../guidelines/rules_of_mdn_documenting/index.html | 193 ----- files/zh-cn/mdn/guidelines/style_guide/index.html | 784 --------------------- .../mdn/guidelines/writing_style_guide/index.html | 784 +++++++++++++++++++++ files/zh-cn/mdn/kuma/index.html | 24 - .../simple_live_sample_demo/index.html | 31 - .../macros/commonly-used_macros/index.html | 222 ++++++ .../mdn/structures/macros/custom_macros/index.html | 222 ------ files/zh-cn/mdn/yari/index.html | 24 + 33 files changed, 1475 insertions(+), 2777 deletions(-) create mode 100644 files/zh-cn/mdn/at_ten/index.html delete mode 100644 files/zh-cn/mdn/community/conversations/index.html delete mode 100644 files/zh-cn/mdn/community/doc_sprints/index.html delete mode 100644 files/zh-cn/mdn/community/index.html delete mode 100644 files/zh-cn/mdn/community/whats_happening/index.html delete mode 100644 "files/zh-cn/mdn/community/\345\234\250\347\244\276\345\214\272\345\267\245\344\275\234/index.html" create mode 100644 files/zh-cn/mdn/contribute/howto/add_or_update_browser_compatibility_data/index.html create mode 100644 files/zh-cn/mdn/contribute/howto/create_an_interactive_exercise_to_help_learning_the_web/index.html delete mode 100644 files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html delete mode 100644 files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html delete mode 100644 files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html delete mode 100644 files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html delete mode 100644 files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html delete mode 100644 files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html delete mode 100644 "files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" delete mode 100644 "files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/index.html" delete mode 100644 "files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" delete mode 100644 files/zh-cn/mdn/editor/basics/index.html delete mode 100644 files/zh-cn/mdn/editor/basics/page_controls/index.html delete mode 100644 files/zh-cn/mdn/editor/basics/page_info/index.html delete mode 100644 files/zh-cn/mdn/editor/edit_box/index.html delete mode 100644 files/zh-cn/mdn/editor/index.html delete mode 100644 files/zh-cn/mdn/editor/source_mode/index.html delete mode 100644 files/zh-cn/mdn/guidelines/content_blocks/index.html create mode 100644 files/zh-cn/mdn/guidelines/does_this_belong_on_mdn/index.html delete mode 100644 files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html delete mode 100644 files/zh-cn/mdn/guidelines/style_guide/index.html create mode 100644 files/zh-cn/mdn/guidelines/writing_style_guide/index.html delete mode 100644 files/zh-cn/mdn/kuma/index.html delete mode 100644 files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html create mode 100644 files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html delete mode 100644 files/zh-cn/mdn/structures/macros/custom_macros/index.html create mode 100644 files/zh-cn/mdn/yari/index.html (limited to 'files/zh-cn/mdn') diff --git a/files/zh-cn/mdn/at_ten/index.html b/files/zh-cn/mdn/at_ten/index.html new file mode 100644 index 0000000000..fa9ddcf29d --- /dev/null +++ b/files/zh-cn/mdn/at_ten/index.html @@ -0,0 +1,37 @@ +--- +title: Mozilla开发者网络10周年 +slug: MDN_at_ten +translation_of: MDN_at_ten +--- +
为我们web技术的文档化走过10年而庆祝！
+ +
+
+

MDN历史

+ +

2005年初，一个理想者组成的小团队建立起来并开始为所有的Web开发者提供实时、免费和社区驱动的在线资源.。他们杰出而不寻常的想法逐渐演化成了今天的Mozilla开发者网络——一个领先和全面的开放Web技术资源库。十年后, 我们全球化的社区变得更加的强大, 同时，为了能给广泛的网络技术公司提供技术上的支持，我们还坚持编写文档, 案例代码 以及学习资源 ，其中就包括像 CSS, HTML, JavaScript 以及各种能够使得网络变得更加强大的东西。

+ +

了解更多about the history

+ + +

为MDN做出贡献

+ +

十年来，MDN社区已经几乎给开放网络贡献了无限多的文档，从最小的字符修改到编写整个一系列新的API，对开放网络，社区中的每个人都有贡献，每个人既不会付出太多也不会太少。我们已经有超过90000页的文档或内容被社区中突出的智谋人（Mozillians）编辑或者被翻译。你将会成为我们中的一员。

+ +

了解更多about contributing

+ +

 

+ +

 

+
+ +
{{TenthCampaignQuote}}
+ +

子目录

+ +
    +
  1. MDN10周年
    2. +
  2. MDN历史
    3. +
  3. 为MDN贡献
    4. +
+
diff --git a/files/zh-cn/mdn/community/conversations/index.html b/files/zh-cn/mdn/community/conversations/index.html deleted file mode 100644 index e37d40486e..0000000000 --- a/files/zh-cn/mdn/community/conversations/index.html +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: MDN 社区对话 -slug: MDN/Community/Conversations -tags: - - 不完善的 - - 后期还需要改善 - - 社区相关 - - 经过一次润色的 -translation_of: MDN/Community/Conversations ---- -
{{MDNSidebar}}
- -

MDN的“工作”在MDN网站开展，但“社区”也通过（异步）讨论以及（同步）在线聊天和会议开展。

- -

异步讨论

- -

为了分享信息并进行持续的讨论，MDN在Mozilla话语论坛中有自己的类别（“MDN”）。 将此类别用于与MDN相关的所有主题，包括文档内容的创建，翻译和维护; MDN平台开发; 并进行规划，目标设定和进度跟踪。

- - - -

历史档案

- -

在2017年6月之前，MDN相关的讨论发生在与Google群组关联并归档的邮件列表中。 如果您想搜索这些过去的讨论，您可以查看与旧邮件列表相对应的Google网上论坛。 （是的，我们知道这些名字是重叠和混淆。历史的偶然性。对此我们感到很抱歉。）

- -
-
mozilla.dev.mdc
-
此列表用于讨论MDN上的文档内容。
-
mozilla.dev.mdn
-
此列表涉及MDN底层Kuma平台的开发工作。
-
mozilla.mdn
-
这个论坛是针对高层次的规划和优先级讨论，MDN网站和其他相关举措。
-
- - - -

同步聊天

- -

Mozilla实时的讨论平台是Matrix，Mozilla自己拥有使用这个通讯协议的服务器。网页中即可加入讨论。

- -

MDN Web文档聊天室是为讨论MDN内容的主要频道。我们探讨编写、内容编排等内容。我们也会进行“茶水间”讨论（摸鱼），这是我们的社群保持联系，或者仅仅用来消遣的方式。通常在北美和欧洲的工作日，这间聊天室最为活跃。

- -

你或许会想了解一下怎么使用Mozilla的Matrix，然后呢，如果你真的很喜欢它的话，那么可以安个独立的Matrix应用，例如Riot.im。

- -

那么IRC呢？

- -

多年来，Mozilla用互联网中继聊天（IRC）来进行实时讨论。到了2020年初，Matrix已经把IRC淘汰了。你可能会在很多地方看到有人提到IRC的频道，包括MDN上。你可以帮忙更新MDN上你看到的IRC频道的链接，为指向对应Matrix聊天室的链接。如果你不确定这个话题对应的Matrix聊天室是哪间，那么可以来General聊天室询问。不再活跃的项目和话题可能也不会有Matrix聊天室，如果是这样的话，把链接删掉即可。

- -

参加我们的会议（和其他活动）

- -


- MDN团队会举行一些面向MDN社区的定期会议。查看 Mozilla维基上的MDN Meetings 页面获取关于日程、议程和笔记的细节，以及如何参加的信息。

- -

查看MDN Events calendar上的这些和其他会议、当地聚会和其他项目。在 MDN Meetings wiki page上有定期会议

- -

如果你看到一个在Vidyo videoconferencing系统的“mdn”频道举行的会议，你可以在网上加入谈话。

diff --git a/files/zh-cn/mdn/community/doc_sprints/index.html b/files/zh-cn/mdn/community/doc_sprints/index.html deleted file mode 100644 index ca1da4be91..0000000000 --- a/files/zh-cn/mdn/community/doc_sprints/index.html +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Doc sprints -slug: MDN/Community/Doc_sprints -tags: - - NeedsUpdate -translation_of: MDN/Community/Doc_sprints ---- -
{{MDNSidebar}}
- -

{{ draft() }}

- -
-

Note: MDN社区在2010 - 2013年期间经常举办文档迭代。 从2014年开始，这些事件的范围扩大到“Hack on MDN”事件，其中包括代码窃取以及文档项目。 下面的大部分建议同样适用于 "Hack" sprints和documentation sprints。

-
- -

这是组织documentation sprint的指南。 它包含来自组织doc sprints的人的建议和提示，以帮助您更好的组织文档。 本指南还借鉴了FLOSS手册书籍的书籍。

- -

什么是 doc sprint?

- -

doc sprint 是一段时间，一群人像你一样可爱的人，合作撰写关于给定主题或相关主题的文档。

- -

sprints 的分类

- -

sprints可以是线上的，也可以是线下的，也可以线上线下一起进行。对于线上sprints而言，每个人都可以在不同的地区参与，只需要通过中间渠道进行沟通。对于线下sprints，参加者在sprints期间聚集在同一地区，以便他们可以面对面进行交流。线下sprints需要更多的后勤规划，确保会议地点，可以容纳所有参与者，并且在sprints期间需要提供食物与安置参与者。

- -

另一种分类sprints的方式是通过专题聚焦。例如sprint可能关注特定的主题，比如：Web开发，或翻译特定语言。

- -

计划一次 sprint

- -

设定目标

- -

明确这次 sprint的目标, 包括内容和社区效应。 这能够帮助你更好地计划低层次的细节。

- - - -

决定类型和范围

- -

基于你的目标, 确定 sprint的类型 (线上的，也可以是线下的，或者是线上线下一起进行) 和范围 (这是参与者会关注的)。

- -

比如说，你想要吸引新的社区成员，你可以选择本地的线下sprint, 因为不需要长途旅行, 而且参加者还可以见面. 如果您想要专注于特定的主题领域，其中内容贡献者是地理上分离的，而且早就彼此认识，那么一个线上sprint就很合适。

- -

选择日期和时间

- -

对于需要长途交通的线下sprint， 我们已经发现了三天 (比如说两天周末和一天工作日) 就足够做到很多重要的工作。也不会占用大家日常生活的很多时间。对于公开，本地，线下的sprint，大部分人只能够付出一天的时间. 对于线上的sprint, 我们通常进行两天: 一个工作日外加周末的一天。 As an alternative example, in the past there has been mini-sprint for writing and translating docs, every Wednesday evening in the Mozilla Paris office; it was primarily in-person for locals, but also got remote participation from Montreal (where it was at lunch time).

- -

Attaching a sprint to the end of a conference that everyone attended worked well; trying to run a sprint during a conference that everyone attended did not work so well. Make sure that participants know about the sprint when they make their conference plans, so that they allow extra days for the sprint.

- -

Consider the time zones that virtual participants are in; be sure that you allow enough working time in each time zone, and have some overlap when multiple zones (such as Europe and Americas, or Americas and Asia) are awake. However, it's just reality that no one time is good for everyone everywhere.

- -

For virtual sprints, the dates can be set as little as 2-3 weeks in advance. For in-person sprints, you need to decide further in advance, in order to allow time for people to decide and make travel arrangements.

- -

Promote the sprint

- -

You can make the sprint open, and invite the world, but you should have a few key people that you know for sure will participate. Work with them when selecting dates, to ensure that they are available during the chosen dates. If the sprint is not open, then you need only extend invitations; make sure that each invitation is personal, explaining why that person has been specificallly invited.

- -

For public sprints, identify existing groups that have an interest in the topic, for example: local Web developer meetup groups for a local in-person sprint. Send an announcement through whatever channel is appropriate for that group. Be sure to provide a link to a web page with more details, and include a call-to-action for people to sign up for the sprint. Eventbrite and Lanyrd are two services that support sign-ups. For Mozilla developer events, we have found that about half the people who sign up actually show up.

- -

Use the social media channels that are appropriate to reach your target attendees. We have found that for Web developers, this means Twitter, followed by Google Plus, more than Facebook or LinkedIn. However, popular channels can vary geographically (such as Orkut in Brazil). Reach out to a few well-connected people who have a large following among your target audience, and ask them to re-share your posts.

- -

Logistics for in-person sprints

- -

Logistics for in-person sprints are greater for longer sprints and those where sprinters travel to attend. A short or locals-only sprint need relatively little logistical support.

- -

Budget and funding

- -

You need to figure out how much the event is going to cost, and where the money is going to come from.

- -

Costs to consider in your budget include:

- - - -

Some of these costs can be self-funded by participants, meaning that they pay for their own costs. There are a variety of ways to save money, which are mentioned in the following sections.

- -

It may be possible to get sponsorship from Mozilla to fund some of the costs of your event. It helps to have a clear focus for your event, and a specific plan and budget. If there is a Mozilla Rep in your area, work with them to request budget and swag through the Reps program. Otherwise, you can submit a developer events request in Bugzilla.

- -
-
Venue
-
There are lots of options for meeting space. If you are in a city with a Mozilla office, you can use the community space in that office. Elsewhere, options include meeting rooms in libraries, churches, coffee shops, or businesses where you have contacts. Many cities now have coworking spaces that rent their conference rooms for a reasonable fee.
-
Resources
-
Be sure that your venue has good chairs and tables, and reliable power and Internet access. Sitting all day on a bad chair is not just uncomfortable; it can lead to injury. Make sure that the number of sprinters and their computers and devices does not overwhelm the power supply and available Internet bandwidth. Be generous (but not dangerous) with extension cords, and if necessary, international plug adapters. A projector for shared viewing can be very helpful. Whiteboards and sticky notes are great for brainstorming and planning.
-
Travel
-
Travel is relevant only if the sprinters do not all live close to the sprint venue. The usual strategies for saving on travel apply, and are not specific to doc sprints.
-
Accommodations
-
Where sprinters stay should not be inconveniently far from the meeting venue. It can be cheaper (and possibly more fun) to split the cost of a vacation house or flat, rather than paying for individual hotel rooms. If you have a mix of visitors and (willing) locals, the visitors can stay in the homes of local community members.
-
Food
-
Sprinters need to eat! Make arrangements for food during the sprint, and inform sprinters if certain meals will not be arranged. If the group is staying in a home, you can save money by buying and cooking food rather than going out to eat. Even if food is self-funded, it can reduce hassle to pitch into a common fund for food, rather than splitting every restaurant bill. If your venue allows, have snacks (some healthy and some not) available between meals.
-
Fun
-
Make time for non-writing social activities. These can be informal, like going for a hike together, or more formal, like a tourist excursion. Going out for beer (at the end of the day, of course) is usually a winner. On the other hand, don't plan every hour of every day. Everybody needs some down time, especially introverts.
-
- -

During the sprint

- -

Planning the work

- -

 

- -

Tracking tasks

- -

Have a way to track what tasks need to be worked on, who is doing what, and what has been completed. For MDN doc sprints, we use a wiki page for advance planning, and an etherpad for tracking work during the sprint.

- -

Often, people want to help but don't know where to start, and deciding among many options takes too much mental effort. For any given participant, give them a couple of possible tasks ("you could do A, or B"); this simplifies their choice, without making them feel like they're being bossed around.

- -

Collaborating

- -

One of the benefits of in-person sprints is that people can work together in ways that they might not be able to when they're not in the same place, for example, by working out ideas together on a whiteboard or by brainstorming with sticky notes. Still, there are opportunities for collaboration and camaraderie in any type of sprint. Chatting via IRC is essential for virtual sprints, and still very helpful for in-person sprints (for example, for sharing links). For a greater sense of "virtual presence", consider using a video conferencing service, such as Google Hangout.

- -

As an organizer, look for common interests among the participants and for ways that they can work together.

- -

Celebrating accomplishments

- -

Be sure to take time to celebrate accomplishments at the end of the sprint. This gives participants a better feeling than when the sprint just ends without any summary. If possible, have people "demo" what they have done, even if it is just showing a new article page.

- -

Also, share the sprint accomplishments via a blog post, to celebrate publicly as well. This is important for any kind of sprint, but especially for virtual sprints, where the participants might not all be online at the official end of the sprint for a wrap-up session.

diff --git a/files/zh-cn/mdn/community/index.html b/files/zh-cn/mdn/community/index.html deleted file mode 100644 index 19e3e729ce..0000000000 --- a/files/zh-cn/mdn/community/index.html +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 加入 MDN 社区 -slug: MDN/Community -tags: - - MDN Meta - - 引导 - - 社区 -translation_of: MDN/Community ---- -
{{MDNSidebar}}
- -
{{IncludeSubnav("/zh-CN/docs/MDN")}}
- -
-

MDN（Mozilla Developer Network）不仅仅是一个维基，而且是一个为使用开放 Web 技术的开发者而打造的社区。在这儿，开发者为了使 MDN 更加出色而共同努力。

-
- -

我们非常乐意您能给 MDN 贡献一份力量。当然我们更加希望您能加入 MDN 社区。只需简单的三步，即可加入我们：

- -
    -
  1. 创建 MDN 账户
    2. -
  2. 参与交流
    3. -
  3. 关注正发生的一切
    4. -
- -

社区是怎么运作的

- -

下列文章详细地介绍了 MDN 社区。

- -
-
-
-
社区参与者
-
MDN 社区有许多负责任的参与者。
-
文档迭代
-
这是一个有关组织文档迭代的指导。它包含组织过文档迭代的开发者的建议和技巧，这个指导的目的是为了帮助您更好地组织文档。
-
关注正发生的一切
-
MDN 是由 Mozilla 开发者网络社区 发起的。这里有一些有关我们正在做的事物信息。
-
- -
-
-
- -
-
-
MDN 社区对话
-
MDN 上的工作在 MDN 社区网站上进行。但社区也提供讨论，在线交流和线下会议等多种对话方式。
-
社区工作
-
了解如何作为 MDN 社区的一部分来为 MDN 文档作贡献是本文的主题。本文给出了一些技巧来帮助您和其他开发者、开发团队来进行更有效的交流。
-
-
-
diff --git a/files/zh-cn/mdn/community/whats_happening/index.html b/files/zh-cn/mdn/community/whats_happening/index.html deleted file mode 100644 index abdb8b5215..0000000000 --- a/files/zh-cn/mdn/community/whats_happening/index.html +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: 跟随正在发生的事情 -slug: MDN/Community/Whats_happening -tags: - - MDN Meta - - 初学者 - - 指南 - - 社区 -translation_of: MDN/Community/Whats_happening ---- -
{{MDNSidebar}}
- -

MDN是由 Mozilla开发者网络社区带给你的。这里是关于我们正在做之事的共享信息的一些途径。

- -

博客

- -
-
Mozilla Hacks
-
Web和Mozilla技术和功能的新闻深度报道。
-
Engaging Developers
-
促进社区参与Mozilla MDN活动和讨论。
-
- -

信息流

- - - -

状态栏和仪表盘

- -

查看 文档状态 页面，以了解整个MDN内容的动态。您将能够看到哪些文章需要书写或更新，哪些主题需要最大的帮助以及更多。

- -

MDN会议

- -

有一些跟踪和各种MDN相关的项目和进程共享进步定期会议，这些都描述了MDN会议的维基页面。

- -

想要了解最新动态，MDN社区会议是最佳渠道。MDN社区会议一般在美国太平洋时间周三上午10点举办（UTC-0800 十月——三月, UTC-0700 三月——十月）。会议每两周举办一次，会议采用 #mdn IRC 的方式举行。想要了解会议日程及往期会议记录，请查阅 MDN 社区会议 维基页面。

- -

公共 MDN活动  日历包括MDN社区会议，文件分享，其他MDN相关活动。如果您在我们的Vidyo视频会议系统中遇到正在“mdn”频道中举办的会议，那么您可以 从从网站上加入会议对话。

diff --git "a/files/zh-cn/mdn/community/\345\234\250\347\244\276\345\214\272\345\267\245\344\275\234/index.html" "b/files/zh-cn/mdn/community/\345\234\250\347\244\276\345\214\272\345\267\245\344\275\234/index.html" deleted file mode 100644 index e8cce689d8..0000000000 --- "a/files/zh-cn/mdn/community/\345\234\250\347\244\276\345\214\272\345\267\245\344\275\234/index.html" +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: 社区工作 -slug: MDN/Community/在社区工作 -tags: - - 指南 - - 社区 -translation_of: MDN/Community/Working_in_community ---- -
{{MDNSidebar}}
- -

在任何重大规模上为MDN文档作出贡献的主要部分是知道如何作为MDN社区的一部分工作。本文提供的技巧可帮助您充分利用与其他作者和开发团队的互动。

- -

一般礼仪准则

- -

以下是在Mozilla社区工作时的一些通用指导原则。

- - - -

委婉

- -

与他人沟通时要时刻保持委婉和恭敬。

- -

礼貌地指出错误

- -

如果您在联系某人的目的是要求他们采取不同的做法，或者指出他们所犯的错误（特别是他们反复犯错的话），请以正面评论开始您的信息。这可以减轻打击，这可以说，它表明你试图帮助，而不是让你成为坏人。 例如，如果一个新的贡献者创建了大量没有标签的页面，并且您想要指出这个问题，那么您给他们的消息可能看起来像这样（您需要为每个个案更改的内容加下划线):

- -
-

嗨，MrBigglesworth，我一直注意到你对Wormhole API文档的贡献，并且能够得到你的帮助真是太棒了！我特别喜欢你通过可读性平衡细节水平的方式。尽管如此，如果您在页面中添加正确的标签，您可以使这些文章更好，更有用。

- -

详细信息，请参阅MDN标记指南 (https://developer.mozilla.org/en-US/docs/MDN/Contribute/Howto/Tag) 。

-
- -

分享知识

- -

在您参与MDN项目时，了解发生了什么以及与我们社区的其他成员进行互动很有用。通过与我们社区中的其他人交谈，您可以获得并分享想法，状态更新等。我们还拥有工具和信息资源，可以帮助您了解由谁来完成的工作。

- -

沟通渠道

- -

您可以通过多种方式与社区成员（开发人员或作者）进行交流，每种方式都有自己特定的礼仪规则。

- -

Bugzilla

- -

在编写文档以涵盖由于Bugzilla中的错误而实施的更改时，您经常会与涉及这些错误的人员进行交互。请务必始终牢记Bugzilla礼仪指南！

- -

电子邮件

- -

有时候，如果你有他们的电子邮件地址，你和一个或多个其他人之间的私人电子邮件交换就是要走的路。

- -
-

注意：一般来说，如果有人在您要记录的技术文档上发布了他们的电子邮件地址，已经亲自给您发送了他们的电子邮件地址，或者通常有一个众所周知的电子邮件地址，则电子邮件是可接受的“第一次联系人”做法。如果你需要挖掘它，你可能应该首先尝试获得IRC或邮件列表的许可，除非你已经用尽了所有其他尝试取得联系的努力。

-
- -

Content status tools

- -

We have several useful tools that provide information about the status of documentation content.

- -
-
Revision dashboard
-
The revision dashboard provides a fantastic tool to review changes made to MDN content. You can see recent history, choose a range of time to view, and filter based on things like locale, contributor's name, and topic. Once you're looking at a set of revisions, you can view the changes made in each revision, quickly open the page, see a full history, or even revert the changes (if you have those privileges).
-
Documentation status overview
-
Our documentation status overview page provides a list of all the areas of MDN that have been configured for status tracking, with information about how many pages therein need different types of work done. Click through to a particular topic area to see detailed lists of content that needs work, such as pages that have no tags, or are tagged with indicators that certain types of work need to be done. You can even see lists of pages that haven't been updated in a long time and may be out of date, as well as a list of bugs that have been flagged as impacting the documentation in that area.
-
Documentation project plans
-
We have a number of writing projects that are in the planning stages, or are large and ongoing, for which we have written planning documents to help us keep track of what we need to get done.
-
MDN Taiga
-
The MDN staff writers use a tool called Taiga to manage current and future documentation projects. You can take a look to see what we're doing and how it's going, and you can see what projects we'd like to see happen soon. Some of those will be taken on by staff writers, but you should feel free to take one over if you like! For more information about the agile processes followed by the MDN team, see our Process page on the Mozilla wiki.
-
- -

The development community

- -

Possibly the most important relationships to develop and maintain, as a member of the MDN writing community, are those you develop and sustain with the developers. They create the software we're developing, but they're also the most useful source of information we have. It's crucial that we maintain good relations with developers—the more they like you, the more likely they are to answer your questions quickly, accurately, and thoroughly!

- -

In addition, you represent the MDN writing community. Please help ensure we keep our excellent working relationship with the dev team by making every interaction they have with the writing team be a good one.

- -

On a related note, a great way to find the right person to talk to is to look at the module owners lists.

- -

The writing community

- -

The writing community is a large one. While the number of extremely frequent, or large-scale contributors is relatively small, there are many dozens or hundreds of people who contribute at least now and then. Fortunately, these are by and large awesome people with a genuine love of the Web, Mozilla, and/or documentation, and interacting with them is almost always pretty easy.

- -

See the article Join the community for more information about the MDN community.

- -

The most frequent place you'll directly interact with other writers is in the {{IRCLink("mdn")}} channel on IRC. This channel is specifically reserved for discussing documentation. For IRC-specific etiquette tips, see the Mozilla Support article "Getting Started with IRC." You'll also have discussions with us on the MDN discussion forum. In general, IRC tends to be used for quick, more in-person-like discussions, while the discussion forum is typically used for longer-duration conversation.

- -

By keeping in mind the {{anch("General etiquette guidelines")}}, you'll find that usually things go very smoothly.

- -

See also

- - diff --git a/files/zh-cn/mdn/contribute/howto/add_or_update_browser_compatibility_data/index.html b/files/zh-cn/mdn/contribute/howto/add_or_update_browser_compatibility_data/index.html new file mode 100644 index 0000000000..8c0513d654 --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/add_or_update_browser_compatibility_data/index.html @@ -0,0 +1,30 @@ +--- +title: 如何添加或更新浏览器兼容性数据 +slug: MDN/Contribute/Howto/如何添加或更新浏览器兼容性数据 +translation_of: MDN/Contribute/Howto/Add_or_update_browser_compatibility_data +--- +
{{MDNSidebar}}

如果你有浏览器在兼容Web特性方面的信息 —— 或者有意愿并有能力做一些这方面的研究和/或实验 —— 你可以帮助更新MDN的浏览器兼容性数据库（BCD）。

+ + + +
+
哪些地方需要做？
+
+

在MDN上你有这几种方法可以帮助改进浏览器兼容性方面的信息：

+ +
    +
  • 添加尚未收录在BCD仓库内的网页特性数据
    • +
  • 依据浏览器新版本的变更内容、现有数据中的更正错误，或者某项技术的特性之最新变更等信息来更新现有数据
    • +
  • 提交 pull requests 到 BCD issues filed on Github.
    • +
+
+
做这个任务你需要知道哪些知识？
+
做这个任务需要哪些步骤？
+
欲了解如何更新在GitHub上的组成BCD仓库的 JSON 文件的详细信息，请参见兼容性表格页面。如要了解我们特别寻求帮助的问题列表，请到 Github issues with the "Help Wanted" tag.
+
 
+
 
+
diff --git a/files/zh-cn/mdn/contribute/howto/create_an_interactive_exercise_to_help_learning_the_web/index.html b/files/zh-cn/mdn/contribute/howto/create_an_interactive_exercise_to_help_learning_the_web/index.html new file mode 100644 index 0000000000..91b8a8640d --- /dev/null +++ b/files/zh-cn/mdn/contribute/howto/create_an_interactive_exercise_to_help_learning_the_web/index.html @@ -0,0 +1,185 @@ +--- +title: 如何创建一个交互学习环境 +slug: MDN/Contribute/Howto/学习_交互_在线_起步_开始 +tags: + - MDN Meta + - 交互 + - 如何使用 + - 学习 + - 教程 +translation_of: MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web +--- +
{{MDNSidebar}}

动态的内容对于学习 Web 来说是重要的。 她能让学习的人更加积极主动。 这可以是练习，实例，任务，评价等等。总之，任何有助于学习理解的东西都行。

+ +

这儿还没有能够直接创建动态的实例内容。但是一些第三方工具可以帮助你创建（如： JSFiddle，CodePen，Dabblet，等），你可以将其链接放在 MDN 文章中。另外，你可以使用 WebMaker 项目的 Thimble 来创造更加高级的内容。

+ +

目前，MDN 虽然没有能够轻易创建动态实例内容的工具。不过，如果你是工程师，可以使用当前 MDN 提供的功能创建自定义的主动学习内容，下面内容将告诉你如何操作。

+ +

MDN live samples

+ +

MDN 有一个非常炫酷的功能：live samples。她是一种可以将 MDN 页面内任何 HTML, CSS, Javascript 代码等效执行的机制。在使用她以前，你最好通读一下 Using the live sample system，这是我们关于她的完整文档。虽然她很容易使用，不过通过阅读文档，你会学到一些奇淫巧技。

+ +

有意思的是，将任何类型的工具或实例嵌入到 MDN 页面中都可以通过调教她轻松做到。

+ +

隐藏代码

+ +

通过实例创建主动学习内容的第一种方法是编辑要添加内容的页面。使用 Live Sample 功能创建内容，只构建你需要的功能，不要在乎代码的复杂度。当内容准备好之后，只需切换到编辑器视图，并用 class 为 hidden 的 {{HTMLElement('div')}} 来包围你的代码。这样代码就会隐藏，不过实例依然可以访问和显示。

+ +

看看这个简单的代码：

+ +
+

点击这个方块提供随机色，或者直接输入色值

+ + +{{EmbedLiveSample('hidden_code_example', 120, 120)}}
+ +

如果你使用 MDN 编辑器查看该页面代码，你会看到如下 HTML 代码：

+ +
<div class="moreinfo">
+<p>Click on the following square to randomly change its color or just type an hexadecimal code color</p>
+
+<div class="hidden">
+<h4 id="hidden_code_example">hidden code example</h4>
+
+<h5 id="HTML">HTML</h5>
+
+<pre class="brush: html">
+&lt;div class="square"&gt;
+  #&lt;input class="color"&gt;
+&lt;/div&gt;</pre>
+
+<h5 id="CSS">CSS</h5>
+
+<pre class="brush: css">
+body {
+  padding: 10px;
+  margin : 0;
+}
+
+.square {
+  width  : 80px;
+  height : 80px;
+  padding: 10px;
+  background-color: black;
+  color: white;
+  text-align: center;
+}
+
+.color {
+  width: 60px;
+  text-transform: uppercase;
+}
+</pre>
+
+<h5 id="JS">JS</h5>
+
+<pre class="brush: js">
+function setColor(color) {
+  document.querySelector('.square').style.backgroundColor = '#' + color;
+  document.querySelector('.color').value = color;
+}
+
+function getRandomColor() {
+  var color = Math.floor(Math.random() * 16777215);
+  return color.toString(16);
+}
+
+function getInputColor() {
+  var value = document.querySelector('.color').value;
+  var color = Number('0x' + color);
+  if (color === +color) {
+    return color.toString(16);
+  }
+  return value;
+}
+
+document.addEventListener('click', function () {
+  setColor(getRandomColor());
+});
+
+document.addEventListener('keyup', function () {
+  setColor(getInputColor());
+});
+</pre>
+</div>
+
+\{{EmbedLiveSample('hidden_code_example', 120, 120)}}
+</div>
+ +

你可以在 the Canvas API page 查看更多高级例子。

+ +

外部代码

+ +

前面的例子在你想嵌入主动学习内容时是可行的。不过，如果你想要处理更加复杂的代码，这个 hidden 的 {{HTMLElement('div')}} 就比较麻烦。

+ +

另外种方案是将内容写入 MDN 页面，然后嵌入另一个页面中。为此，我们可以使用 {{TemplateLink("EmbedDistLiveSample")}} 替代{{TemplateLink("EmbedLiveSample")}} 。

+ +

我们学习配置这个模拟远程代码嵌入的实例：

+ +
+

点击这个方块提供随机色，或者直接输入色值

+{{EmbedLiveSample('The_example', 120, 120, '', 'MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example')}}
+ +

这下如果你继续使用 MDN 编辑器查看页面源码，将看不到隐藏元素。如果你需要看，则需要前往这个页面地址。

+ +

你可以在 HTML 表单教程中查看更多高级例子，那里可以使用表单尝试。

diff --git a/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html b/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html deleted file mode 100644 index 256d61b897..0000000000 --- a/files/zh-cn/mdn/contribute/howto/create_an_mdn_account/index.html +++ /dev/null @@ -1,44 +0,0 @@ ---- -title: 如何创建 MDN 账号 -slug: MDN/Contribute/Howto/Create_an_MDN_account -tags: - - MDN - - 创建账户 - - 初学者指南 - - 新手上路 -translation_of: MDN/Contribute/Howto/Create_an_MDN_account ---- -
{{MDNSidebar}}
- -

 要对MDN的内容进行任何更改，你需要一个MDN账户。别担心，如果你只是打算阅读或搜索MDN，就不需要一个账户！这个指南  将帮助你建立MDN账户。

- -
-
-

为什么MDN需要我的电子邮件地址？

- -

你的电子邮件地址用于帐户恢复；必要时，MDN管理员会通过它来联系您，讨论你的账户或在网站上的活动。

- -

此外，你可以选择订阅通知（例如，当特定的页面被更改）和消息（例如，如果你选择加入我们的beta测试团队，你可能会收到关于待测试新功能的邮件）。

- -

你的电子邮件地址永远不会显示在MDN，并只会按照我们的隐私政策使用。

- -
如果你通过Github登录到MDN，并且你的Github账号使用了“noreply”的电子邮件地址，你将不会收到任何来自MDN的信息（包括你从页面订阅的通知）。
-
-
- -
    -
  1. 在每个MDN页面的顶部都有一个登录按钮。将鼠标指向它（如果你在移动设备上使用，轻触即可），以显示支持的登录到MDN的认证服务列表。
    2. -
  2. 选择一项服务以登录。目前，我们只支持使用Github登录。值得注意的是如果你选择GitHub，你的MDN公开资料页上将显示一个链接，其指向你的GitHub个人资料页。
    3. -
  3. 按照Github的提示，将你的GitHub帐户绑定到MDN。
    4. -
  4. 从认证服务页面返回到MDN之后，MDN会提示你输入用户名和电子邮件地址。你的用户名会公开显示，以便展示你做过的工作。请不要将你的电子邮件地址作为用户名。
    5. -
  5. 点击创建我的MDN个人资料。
    6. -
  6. 如果你在步骤4中指定的电子邮件地址与认证服务所使用的不同，请检查这个邮箱，并点击我们发送的确认邮件中的链接。
    7. -
- -

一切就绪！你已经拥有一个MDN帐户，并可以立即编辑页面！

- -

你可以在任何MDN页面的顶部点击你的名字以查看账号的公开资料。从那里，你可以点击编辑按钮修改或更新你的个人资料。

- -
-

注：新用户名不能包含空格或“@”字符。请记住，你的用户名将会公开显示，以标识你做过的工作！

-
diff --git a/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html b/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html deleted file mode 100644 index 83945186c5..0000000000 --- a/files/zh-cn/mdn/contribute/howto/do_a_technical_review/index.html +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: 如何进行技术审查 -slug: MDN/Contribute/Howto/Do_a_technical_review -tags: - - MDN Meta - - 复核 - - 如何做 - - 指南 - - 文档 -translation_of: MDN/Contribute/Howto/Do_a_technical_review ---- -
{{MDNSidebar}}
- -

技术复核包括审查一篇文章的技术准确性和完整性，并在必要的时候予以纠正。 如果一篇文章的作者需要其他人来对文章进行技术复核的话，就需要在编辑时勾选”技术复核“选项。通常情况下，作者会联系特定的工程师来执行技术审查，但是任何具有此领域专业技能的人都可以完成技术复核。

- -

本文介绍如何进行技术复核，从而帮助确保MDN的内容的正确性。

- -

任务是什么？

- -

  审查和纠正文章的技术准确性和完整性。

- -

什么地方需要技术审核？

- -

  在被标记为需要技术审核的特定文章中。

- -

开始做任务前你需要了解什么？

- - - -

完成任务的步骤是什么？

- -
    -
  1. 选取一篇需要复查的文章： -
      -
    1. 前往 technical reviews 页面。这里列出了所有需要技术复核的文章。
      2. -
    2. 选择一个你非常熟悉的领域的页面。
      3. -
    3. 点击该页面。
      4. -
    -
    2. -
  2. 在阅读这篇文章的时候注意文章里的所有技术细节：这篇文章的内容正确吗？是否缺少了一些细节？如果你觉得这篇文章不适合你，那么请毫不犹豫地换一篇文章。
    3. -
  3. 如果没有错误，你不需要重新编辑来把这篇文章标识为”已复核“，你只需要找到左边导航栏最下方的”快速复核“框。黄色背景的框里列出了所有等待复核的请求，像这样：
    4. -
  4. 去掉需要技术复核前面的勾，然后点保存。
    5. -
  5. 如果你发现了需要被修正的错误，你可以在编辑器里修改这篇文章的审核请求状态。以下是操作步骤： -
      -
    1. 点击页面顶部的编辑按钮，进入 MDN editor 页面，来编辑该页面。
      2. -
    2. 更正不正确的技术信息，还可以添加文章遗漏的任何重要信息。
      3. -
    3. 在文章的底部输入修改注释。这个注释简要地描述你的修改工作，比如“完成技术审查。”如果你更正了某些信息，将它们写进你的注释，比如“技术审查以及修复参数的相关描述。”这将帮助其他贡献者和网站编辑人员知道你修改的部分以及原因。如果你认为文章中有些不必要被审查的部分，也可以在注释中提出来。
      4. -
    4. 取消勾选“需要审查”下面的“技术”选项框了吗？它就在页面的审查注释区域。
      5. -
    5. 点击发布按钮。
      6. -
    -
    6. -
- -

祝贺你，你已经完成了你的第一篇技术复核，感谢您的帮助！

diff --git a/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html b/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html deleted file mode 100644 index 48396dcd33..0000000000 --- a/files/zh-cn/mdn/contribute/howto/do_an_editorial_review/index.html +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: 如何进行编辑审核 -slug: MDN/Contribute/Howto/Do_an_editorial_review -tags: - - 指导 - - 文档 - - 编辑审核 -translation_of: MDN/Contribute/Howto/Do_an_editorial_review ---- -
{{MDNSidebar}}
- -
{{IncludeSubnav("/zh-CN/docs/MDN")}}
- -

编辑审核的工作由修改文中排版错误，拼写、语法、用法等文本错误构成。并不是所有贡献者都是语言专家，但有了他们的共同努力，他们把那些需要编辑以及校对的文章转化为了极其有用的文章；这些都是在编辑审核的工作中完成的。

- -

这篇文章描述了如何进行编辑审核，从而帮助实现 MDN 的内容精确。

- -
-
任务是什么？
-
编辑并审核那些被标记为需要编辑审核的文章。
-
应该在何处处理它？
-
在特定的文章中会有标记有需要编辑审核的地方。
-
开始做任务前你需要了解什么？
-
你需要有好的中文语法和词汇技能。文章复核是要确保语法、用词都是正确的并且有意义，同时遵循 MDN 样式指南。
-
完成任务的步骤是什么？
-
-
    -
  1. 选择一篇文章来审核： -
      -
    1. 访问需要复核的文章列表。它陈列了所有请求编辑审核的页面。
      2. -
    2. 点击文章链接进入页面。
      - 注意：这个列表是自动生成的，但更新并不频繁，所以列表中的一些文章是不再需要编辑审核的。如果你选择的文章没有显示“这篇文章需要复核”，跳过这一篇文章，再选择其他的文章。
      3. -
    -
    2. -
  2. 仔细阅读文章，特别注意其中可能出现的排版、错字、语法或者词语使用错误。如果你觉得这篇文章不适合你，随时可以换一篇其它文章。
    3. -
  3. 如果文章中没有任何错误，你不需要进入编辑页面再把它标记为“已审核”。在页面的左侧边栏处可以找到“快速复核”对话框：
    - 文法复核边栏屏幕截图
    4. -
  4. 取消 文法 的勾选之后点击 保存 。
    5. -
  5. 如果你发现了需要改正的错误： -
      -
    1. 点击右上角蓝色的 编辑 按钮；它将带你进入 MDN 编辑器。
      2. -
    2. 更正所有你看到的的排版、错字、语法或者词语使用错误。你并不需要将所有问题都一次性改好，不过当完成整篇文章的时候你还觉得不确定是否完美，一定要保留文法复核的请求。
      3. -
    3. 在文本底部输入一段修订注释；比如 “文法符合：更改了排版，语法和用词错误。” 这有助于其他编辑者和网站管理员知道你更改了什么以及为什么做出更改。
      4. -
    4. 在 需要复核吗？ 下面取消 文法 的选择。这一项位于页面的 版本备注 当中。
      - 文法复核编辑模式屏幕截图
      5. -
    5. 点击 发布 按钮。
      6. -
    -
    6. -
- -
-

你所做出的更改在保存后不一定立即可见，页面保存和处理过程可能出现一些延迟。

-
-
-
diff --git a/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html b/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html deleted file mode 100644 index bf90ff0262..0000000000 --- a/files/zh-cn/mdn/contribute/howto/set_the_summary_for_a_page/index.html +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: 如何为页面编写概要 -slug: MDN/Contribute/Howto/Set_the_summary_for_a_page -tags: - - 指南 -translation_of: MDN/Contribute/Howto/Set_the_summary_for_a_page ---- -
{{MDNSidebar}}
- -

您可以在MDN的每一个页面上定义概要，它可以在很多方面起到作用，如包含在搜索引擎的搜索结果中，或者在其他MDN页面如热门话题页或者工具提示页。它应该概括的描述该页面的所有内容，并且当在其他页面显示时，不包含页面内容的无关部分。

- -
-

一个概要可以被明确的定在在一个页面中。如果概要没有被明确的定义，通常会使用该页面内容的第一句话作为概要，而它往往不是该页面最精确的描述。

-
- - - - - - - - - - - - - - - - - - - - -
任务是什么？标记应被用作其在其他情况下摘要页面中的文本;这项任务可能包括在需要写相应的文本。
哪些地方需要它？在缺乏一个总结或总结不太好的页面。
完成任务需要什么？能够使用MDN编辑器的能力;良好的英语写作能力;对网页的主题足够熟悉，以便于能写一个很好的总结。
怎样完成任务？ -
    -
  1. 选择一个页面来设置总结: -
      -
    1. 在MDN documentation status 页面上的section中, 点击你所了解的话题。
      2. -
    2. 在主题的文档状态页面，单击汇总表中的页头。这需要你在该主题区段的所有网页的索引;它示出了在左侧列中的页面的链接，以及在右栏中的标签和摘要。
      3. -
    3. 挑选缺少一个总结页面，或者说有一个较差的总结的页面。
      4. -
    -
    2. -
- -
-

点击链接进入该页面。

-
- -
    -
  1. 单击编辑在MDN编辑器中打开该页面。
    2. -
  2. 找一两句话，作为一个总结。如果需要，可以编辑现有的内容来创建或修改的句子来做一个很好的总结。
    3. -
  3. 选择要使用的摘要文本。
    4. -
  4. 在样式插件的编辑器工具栏，选择搜索引擎优化摘要。 (In the page source, this creates a {{HTMLElement("span")}} element with class="seoSummary" around the selected text.)
    5. -
  5. 保存你的更改，并附上类似“设置页面总结”的修改意见。修改意见是可选的，但我们鼓励你添加一个。这样便于其他人了解变更的情况。
    6. -
-
- -

完成这样的一份任务后，你就是MDN的一员。

diff --git a/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html b/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html deleted file mode 100644 index 4420d3f04e..0000000000 --- a/files/zh-cn/mdn/contribute/howto/tag_javascript_pages/index.html +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: 如何给JavaScript相关页面添加标签 -slug: MDN/Contribute/Howto/Tag_JavaScript_pages -translation_of: MDN/Contribute/Howto/Tag_JavaScript_pages ---- -
{{MDNSidebar}}

标记工作包括给页面添加元信息，使得这些页面的相关内容能被搜索工具等正确的分拣。

- -
-
哪里需要做这件事?
-
那些特定的没有标签的JavaScript相关的页面
-
开始标记任务前你需要知道些什么？
-
一些基本的JavaScript编程知识，比如javascript中的方法和属性都是些什么。
-
你的工作有以下几个步骤
-
-
    -
  1. 选择下面列举的某篇文章。
    2. -
  2. 点击该文章所对应的链接，载入页面。
    3. -
  3. 当页面载入完毕时，点击顶部附近的EDIT按钮，就会进入MDN编辑模式。
    4. -
  4. 最后就是添加Javascript相关的标签了，我们提供了如下可选的标签。 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    标签名适用于含有哪些内容的页面
    Method方法
    Property属性
    Prototype原型
    Object type name所述对象的名字，例如String.fromCharCode就应该有String标签
    ECMAScript6 and Experimental在新版ECMAScript标准中增加的特性
    Deprecated不赞成使用的特性（那些不鼓励使用但仍然被浏览器支持的特性）
    Obsolete被废弃的特性（那些不再被浏览器支持的特性）
    others查看 MDN 标签规则 中其他可选标签
    -
    5. -
  5. 添加备注信息并保存你的修改。
    6. -
  6. 你做到了！
    7. -
-
-
- -

 

diff --git a/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html b/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html deleted file mode 100644 index 15c6f0b2ee..0000000000 --- a/files/zh-cn/mdn/contribute/howto/write_an_article_to_help_learn_about_the_web/index.html +++ /dev/null @@ -1,117 +0,0 @@ ---- -title: 如何写文章帮助人们了解 Web -slug: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web -tags: - - MDN元数据 - - 学习社区 - - 指导 - - 贡献指南 -translation_of: MDN/Contribute/Howto/Write_an_article_to_help_learn_about_the_Web ---- -
{{MDNSidebar}}
- -

MDN 的学习区是我们给新手开发者介绍 Web 概念的大本营。因为它的内容主要面对初学者，这是你分享知识，帮助新手逐渐了解 Web 的绝佳地点。确保新手开发者能够跟上这里的内容是很重要的，所以我们格外重视学习区。

- -

这篇文章解释了如何给学习区写文章。

- -

如何写学习社区的文章

- -

要开始贡献你的知识，只需点击绿色大按钮，然后按照下面的五个步骤。如果你想找点子，请看一下我们的团队 Trello ！

- -
写一篇新的学习文章 - -
-
- -

这篇文章可能不会在正确的地方出现，但至少是在MDN上。如果你需要找人谈谈把它搬到正确的地方，请联系我们。

- -

第一步：写两行

- -

你文章的第一句话需要总结一下你将要涉及的主题，第二句话应该更详细地介绍你要放在文章中的内容（项目）。例如：

- -
-

 {{glossary("HTML")}} 文件包含的结构和内容, {{Glossary("CSS")}}以及其他主要的Web技术，使内容看起来像你想要的那样。在本文中，我们将介绍这项技术是如何工作的，以及如何编写你自己的基本示例。

-
- -

注意示例如何简要说明CSS是用于样式化页面的核心Web技术。 这足以使读者很好地了解本文所涵盖的内容。

- -

因为学习区域的文章主要是针对初学者的，所以每篇文章都应该涵盖一个简单的主题，以免给读者带来太多的新信息。如果你不能在一句话中总结这篇文章，那么你可能在一篇文章中做得太多了!

- -

第二步：添加一个顶部框

- -

然后添加一个顶框，以帮助读者了解他们在学习过程中的位置。 这是“了解URL及其结构 ”顶部框的示例。 您可以在编写自己的文章时将其用作模型。

- - - - - - - - - - - - -
必要条件:您首先必须清楚Internet的工作方式，Web服务器是什么，与Web链接背后的所有概念。
目标:您将了解什么是URL以及它如何在Web上工作
- -
-
必要条件
-
读者首先必须知道什么东西才能读懂你的一篇文章?在有可能的状况下，让每一个前提条件链接到另一篇涵盖概念的学习领域的一篇文章(除了您写的是是一篇完全不需要首先先验知识的无比基础的文章)。
-
目标
-
这一章节粗略说明了您的读者在阅读学习这篇文章的过程中会学到（并学会）什么。这与一行程序有点不同;一行代码总结了文章的主题，而目标部分专门列出了读者在阅读文章过程中所希望完成的全部内容。
-
- -
-

注意:要创建此表，您可以复制并粘贴上面的示例表，或者使用MDN的编辑器 台式工具。如果选择使用table工具，则需要在默认的standard-table类之外特别添加learn-box CSS类。为此，当您创建或编辑表的属性时，请转到“Advanced”面板并将样式表类字段设置为“standard-table learn-box”。

-
- -

第三步:写一个完整的描述

- -

接下来，写一个更长的描述，提供更全面的文章概述，突出最重要的概念。不要忘记解释为什么读者要花时间来学习这个主题并阅读你的文章！

- -

第四步：更深一步

- -
当你完成了所有这些，你终于可以深入到主题。你可以根据自己的喜好来组织文章的这一部分(尽管您能够随时咨询我们的 设计指南)。这是你闪耀的机会!详细解释你要写的主题。提供指向完整参考文档的链接，详细解释该技术的工作原理，提供语法和用法细节，等等。由你决定 - -
-
- - - -

看一看我们的函数的前几节可重用代码块文章 ，有一些很好的描述部分。

- -

第五步:提供“主动学习”材料

- -

为了阐明本文并帮助读者更好地理解他们正在学习的内容，请确保提供练习、教程和需要完成的任务。通过让他们积极地、实际地使用和试验你文章中解释的概念，你可以帮助他们将信息“锁定”在大脑中。

- -

您可以选择在页面中直接包含这些示例作为 实时实例,或者直接链接到它们。 （如果它们不能作为实时实例。） 如果你有兴趣帮助创造这些有价值的东西 ，请参阅《创建一个交互式的练习来帮助学习网络》

- -

如果您不能提供到现有活动学习材料的链接(您不知道或者没有时间创建它们)，那么您应该在文章中添加标记{{tag ("NeedsActiveLearning")}}。这样，其他贡献者就可以找到需要积极学习材料的文章，并可能帮助你找到它们。

- -

看看《主动学习:选择不同的元素》进行现场互动学习练习或者《主动学习: 玩转范围》或者另一种不同风格的练习，要求它们在本地下载模板并按照提供的步骤更改

- -

- -

                                                                                         

- -

第六步：查看文章，并放入学习区域导航菜单

- -

在你写完你的文章后，让我们知道，这样我们可以看一看，做一个回顾，并提出改进建议 。再次看看我们的 联系方式 板块以寻找最好的联系方式。

- -

完成文章的另一部分是把它放在学习区主导航菜单中。这个菜单是 LearnSidebar 宏生成的。 你需要特殊的权限来编辑，所以，再一次，让我们团队中的一个人把它添加进去。

- -

您至少应该将其添加到您的页面中，这是通过在页面顶部的段落中添加宏调用\{{LearnSidebar}}来完成的。

- - - -

推荐文章

- -

您想做出贡献，但是您不知道该写什么?

- -

学习社区维护了一个要写文章的Trello看板。随意挑选一个，然后开始去写吧！

diff --git "a/files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" "b/files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" deleted file mode 100644 index 8c0513d654..0000000000 --- "a/files/zh-cn/mdn/contribute/howto/\345\246\202\344\275\225\346\267\273\345\212\240\346\210\226\346\233\264\346\226\260\346\265\217\350\247\210\345\231\250\345\205\274\345\256\271\346\200\247\346\225\260\346\215\256/index.html" +++ /dev/null @@ -1,30 +0,0 @@ ---- -title: 如何添加或更新浏览器兼容性数据 -slug: MDN/Contribute/Howto/如何添加或更新浏览器兼容性数据 -translation_of: MDN/Contribute/Howto/Add_or_update_browser_compatibility_data ---- -
{{MDNSidebar}}

如果你有浏览器在兼容Web特性方面的信息 —— 或者有意愿并有能力做一些这方面的研究和/或实验 —— 你可以帮助更新MDN的浏览器兼容性数据库（BCD）。

- - - -
-
哪些地方需要做？
-
-

在MDN上你有这几种方法可以帮助改进浏览器兼容性方面的信息：

- -
    -
  • 添加尚未收录在BCD仓库内的网页特性数据
    • -
  • 依据浏览器新版本的变更内容、现有数据中的更正错误，或者某项技术的特性之最新变更等信息来更新现有数据
    • -
  • 提交 pull requests 到 BCD issues filed on Github.
    • -
-
-
做这个任务你需要知道哪些知识？
-
做这个任务需要哪些步骤？
-
欲了解如何更新在GitHub上的组成BCD仓库的 JSON 文件的详细信息，请参见兼容性表格页面。如要了解我们特别寻求帮助的问题列表，请到 Github issues with the "Help Wanted" tag.
-
 
-
 
-
diff --git "a/files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/index.html" "b/files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/index.html" deleted file mode 100644 index 91b8a8640d..0000000000 --- "a/files/zh-cn/mdn/contribute/howto/\345\255\246\344\271\240_\344\272\244\344\272\222_\345\234\250\347\272\277_\350\265\267\346\255\245_\345\274\200\345\247\213/index.html" +++ /dev/null @@ -1,185 +0,0 @@ ---- -title: 如何创建一个交互学习环境 -slug: MDN/Contribute/Howto/学习_交互_在线_起步_开始 -tags: - - MDN Meta - - 交互 - - 如何使用 - - 学习 - - 教程 -translation_of: MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web ---- -
{{MDNSidebar}}

动态的内容对于学习 Web 来说是重要的。 她能让学习的人更加积极主动。 这可以是练习，实例，任务，评价等等。总之，任何有助于学习理解的东西都行。

- -

这儿还没有能够直接创建动态的实例内容。但是一些第三方工具可以帮助你创建（如： JSFiddle，CodePen，Dabblet，等），你可以将其链接放在 MDN 文章中。另外，你可以使用 WebMaker 项目的 Thimble 来创造更加高级的内容。

- -

目前，MDN 虽然没有能够轻易创建动态实例内容的工具。不过，如果你是工程师，可以使用当前 MDN 提供的功能创建自定义的主动学习内容，下面内容将告诉你如何操作。

- -

MDN live samples

- -

MDN 有一个非常炫酷的功能：live samples。她是一种可以将 MDN 页面内任何 HTML, CSS, Javascript 代码等效执行的机制。在使用她以前，你最好通读一下 Using the live sample system，这是我们关于她的完整文档。虽然她很容易使用，不过通过阅读文档，你会学到一些奇淫巧技。

- -

有意思的是，将任何类型的工具或实例嵌入到 MDN 页面中都可以通过调教她轻松做到。

- -

隐藏代码

- -

通过实例创建主动学习内容的第一种方法是编辑要添加内容的页面。使用 Live Sample 功能创建内容，只构建你需要的功能，不要在乎代码的复杂度。当内容准备好之后，只需切换到编辑器视图，并用 class 为 hidden 的 {{HTMLElement('div')}} 来包围你的代码。这样代码就会隐藏，不过实例依然可以访问和显示。

- -

看看这个简单的代码：

- -
-

点击这个方块提供随机色，或者直接输入色值

- - -{{EmbedLiveSample('hidden_code_example', 120, 120)}}
- -

如果你使用 MDN 编辑器查看该页面代码，你会看到如下 HTML 代码：

- -
<div class="moreinfo">
-<p>Click on the following square to randomly change its color or just type an hexadecimal code color</p>
-
-<div class="hidden">
-<h4 id="hidden_code_example">hidden code example</h4>
-
-<h5 id="HTML">HTML</h5>
-
-<pre class="brush: html">
-&lt;div class="square"&gt;
-  #&lt;input class="color"&gt;
-&lt;/div&gt;</pre>
-
-<h5 id="CSS">CSS</h5>
-
-<pre class="brush: css">
-body {
-  padding: 10px;
-  margin : 0;
-}
-
-.square {
-  width  : 80px;
-  height : 80px;
-  padding: 10px;
-  background-color: black;
-  color: white;
-  text-align: center;
-}
-
-.color {
-  width: 60px;
-  text-transform: uppercase;
-}
-</pre>
-
-<h5 id="JS">JS</h5>
-
-<pre class="brush: js">
-function setColor(color) {
-  document.querySelector('.square').style.backgroundColor = '#' + color;
-  document.querySelector('.color').value = color;
-}
-
-function getRandomColor() {
-  var color = Math.floor(Math.random() * 16777215);
-  return color.toString(16);
-}
-
-function getInputColor() {
-  var value = document.querySelector('.color').value;
-  var color = Number('0x' + color);
-  if (color === +color) {
-    return color.toString(16);
-  }
-  return value;
-}
-
-document.addEventListener('click', function () {
-  setColor(getRandomColor());
-});
-
-document.addEventListener('keyup', function () {
-  setColor(getInputColor());
-});
-</pre>
-</div>
-
-\{{EmbedLiveSample('hidden_code_example', 120, 120)}}
-</div>
- -

你可以在 the Canvas API page 查看更多高级例子。

- -

外部代码

- -

前面的例子在你想嵌入主动学习内容时是可行的。不过，如果你想要处理更加复杂的代码，这个 hidden 的 {{HTMLElement('div')}} 就比较麻烦。

- -

另外种方案是将内容写入 MDN 页面，然后嵌入另一个页面中。为此，我们可以使用 {{TemplateLink("EmbedDistLiveSample")}} 替代{{TemplateLink("EmbedLiveSample")}} 。

- -

我们学习配置这个模拟远程代码嵌入的实例：

- -
-

点击这个方块提供随机色，或者直接输入色值

-{{EmbedLiveSample('The_example', 120, 120, '', 'MDN/Contribute/Howto/Create_an_interactive_exercise_to_help_learning_the_web/distant_example')}}
- -

这下如果你继续使用 MDN 编辑器查看页面源码，将看不到隐藏元素。如果你需要看，则需要前往这个页面地址。

- -

你可以在 HTML 表单教程中查看更多高级例子，那里可以使用表单尝试。

diff --git "a/files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" "b/files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" deleted file mode 100644 index 08693b3ff1..0000000000 --- "a/files/zh-cn/mdn/contribute/howto/\346\210\220\344\270\272\344\270\200\345\220\215\346\265\213\350\257\225\347\211\210\350\257\225\351\252\214\345\221\230/index.html" +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: 如何成为一名测试版试验员 -slug: MDN/Contribute/Howto/成为一名测试版试验员 -tags: - - MDN Meta -translation_of: MDN/Contribute/Howto/Be_a_beta_tester ---- -
{{MDNSidebar}}
- -

随着MDN Kuma平台的开发人员不断地对站点进行更改，我们为那些选择成为测试版测试人员提供对这些新特性的早期访问。与任何“beta”测试一样，在某些情况下，一些功能可能无法正常工作。

- -

参与beta测试

- -
    -
  1. 登录MDN，在顶部导航栏点击你的用户名。
    - Shows location of the user's profile link in the top navigation
    - 随后跳转到你的资料页。
    2. -
  2. 点击编辑按钮。
    - Shows location of the button to edit a user's profile (which may vary depending on window dimensions
    - 随后在编辑模式下打开资料页。
    3. -
  3. 勾选复选框成为 Beta 测试者。
    - Shows the location of the Beta Tester checkbox
    4. -
  4. 点击资料页底部的发布按钮
    - Shows the location of the Publish button on a user's profile page
    5. -
- -

退出Beta测试

- -
    -
  1. 登录MDN，在顶部导航栏点击你的用户名。随后会跳转到你的资料页。
    2. -
  2. 点击编辑按钮。随后在编辑模式下打开资料页。
    3. -
  3. 取消 Beta 测试者的复选框
    4. -
  4. 点击发布按钮.
    5. -
- -

对beta测试给予反馈

- -

你有两种方式可以对 beta 测试进行反馈:

- - - -
    -
  1. 如果你还没有账号，创建一个 Bugzilla 账号.
    2. -
  2. 打开 bug report in Bugzilla for MDN.
    3. -
  3. 在“摘要”字段中包含 “beta” 一词，帮助 MDN开发人员过滤和区分传入的 bug。.
    4. -
  4. 尽你所能填写 bug 报告. 越详细越好.
    5. -
  5. 点击提交按钮.
    6. -
- -

 

diff --git a/files/zh-cn/mdn/editor/basics/index.html b/files/zh-cn/mdn/editor/basics/index.html deleted file mode 100644 index d6435b8282..0000000000 --- a/files/zh-cn/mdn/editor/basics/index.html +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: 编辑器 UI 元素 -slug: MDN/Editor/Basics -tags: - - 指南 - - 新手 - - 编辑器 -translation_of: MDN/Editor/Basics ---- -

MDN内置 WYSIWYG（所见即所得）编辑器，目的就是让编辑工作变得更加轻松。你可以轻松地在网站各处创建、编辑、修改文章或其他页面。 编辑器界面如下所示，包含八个关键区域。本指南将提供每个区域的介绍，以便您了解如何使用整个编辑环境。

- -
-

我们不断努力改进MDN，所以有时候本指南或下面的屏幕截图可能会稍微过时。不过，我们会定期更新此文档，以避免其无法使用。

-
- -

Screenshot of the editor UI (August 2017) with each section labeled

- -

上图所示的编辑器各个UI区域已罗列在下表中，点击下面的链接来了解每个部分。

- - - -

修订注释

- -

我们强烈建议你每次编辑完成后要附上对修改的注释（修订注释）。这些注释将被保存到页面的修订历史中，就像这个修订看板。这将有助于向复核你修改的人提供解释说明。想要添加修订意见也很简单，只要在发布之前，在修订意见框中填入注释即可。

- -

这么做的好处：

- - - -

复核请求

- -

MDN社区使用复核来追踪和提高MDN内容的质量。通过在文章页面上设置特定标志来表示这篇文章需要审查复核。你可以在 MDN 使用指南中了解更多关于技术复核和文法复核的知识。

- -

想要申请对你所做的文章进行复核，只需勾选对应复核类型前面的复选框即可。任何对技术方面的修改，都应申请技术复核，当然，如果你申请文法复核，想找个人来检查你的写作和样式，那也是极好的。

- -

当申请复核后，文章将会被添加到需要技术复核或需要文法复核列表，但这并不能保证会立马有人来复核你的文章。对于技术复核，最好直接联系相关技术领域的学科专家。对于编辑评论，您可以在 MDN 论坛中发帖以请求其他人来复核你的更改。

- -

 

- -

在勾选申请复核之后，请务必点击一下发布按钮，这样才能提交复核请求。

- -

参阅

- - - - diff --git a/files/zh-cn/mdn/editor/basics/page_controls/index.html b/files/zh-cn/mdn/editor/basics/page_controls/index.html deleted file mode 100644 index 48175fd7c8..0000000000 --- a/files/zh-cn/mdn/editor/basics/page_controls/index.html +++ /dev/null @@ -1,37 +0,0 @@ ---- -title: MDN 编辑器页面控件 -slug: MDN/Editor/Basics/Page_controls -tags: - - 指南 - - 编辑器 -translation_of: MDN/Editor/Basics/Page_controls ---- -
{{MDNSidebar}}
- -

页面控件由对整个页面起作用的按钮组成，为了减少多余的滚动，页面控件在编辑器的顶部和底部都可见。一共有四个页面控制按钮：

- -
-

如果你编写的页面符合 MDN 的要求，而编辑器却不能保存成功，你可以电子邮件联系开发团队寻求帮助。

-
- -
-
发布并继续编辑
-
点击这个按钮，会在不关闭编辑器的前提下保存并发布页面。这样你就可以定期保存编辑工作，在页面修订历史中创建存档，这些存档说不定以后会用到。在创建新页面时这个按钮是不可用。查看修订注释框以了解如何在保存文章时添加修订注释。
-
发布
-
点击该按钮，将保存并发布你的文章，同时关闭编辑器，浏览器跳转到标准模式下的页面。查看修订注释框以了解如何在保存文章时添加修订注释。
-
预览
-
点击这个按钮将打开新的页面或窗口，以发布的样式展示编辑器中的内容，其中的宏指令和模板都如实展示。值得注意的是，此时你的文章并没有被保存。这个按钮的作用，就是在文章发布前检查实际页面效果的，如果出现脚本错误，请参阅预览页面时排除脚本错误。
-
-
-

警告: Currently some macros and templates don't execute properly in Preview-mode, leaving the Preview page missing some of its content (such as sidebars), and thus with somewhat distorted page layout; i.e. not totally WYSIWYG. Further, if SCAYT is enabled (and possibly if the page contains certain valid macros or templates), Preview mode may still give a scripting error.

-
-
-

- 放弃
-
这个按钮的功能就是取消编辑，放弃所有未曾保存的更改。页面将会跳转回上个页面。
-
-
-

警告: Occasionally Discard can malfunction and start acting more like a partial "discard," undoing many of your changes without exiting the editor. If this happens to you, you should save, exit, and re-enter the editor.

-
-
-
diff --git a/files/zh-cn/mdn/editor/basics/page_info/index.html b/files/zh-cn/mdn/editor/basics/page_info/index.html deleted file mode 100644 index 54be30c0cf..0000000000 --- a/files/zh-cn/mdn/editor/basics/page_info/index.html +++ /dev/null @@ -1,47 +0,0 @@ ---- -title: 编辑器 UI 的页面信息区域 -slug: MDN/Editor/Basics/Page_info -tags: - - 指南 - - 新手 - - 编辑器 -translation_of: MDN/Editor/Basics/Page_info ---- -
{{MDNSidebar}}
- -

页面信息区域包含了本页面的信息，但也可以扩展开来以提供额外的页面控件。

- -

现有页面

- -

默认情况下，编辑现有页面时，页面信息区域会显示页面标题。

- -

你可以点击编辑标题和属性按钮来打开更多页面控件。如下图：

- -

Page info fields for an existing article

- -

这里可以对下列内容进行设置：

- -
-
标题
-
标题会显示在浏览器的标题栏（或标签栏）、面包屑导航栏中，以及文章的顶部。但它不会出现在页面的URL中。
-
目录
-
指定文章中次级标题的级别深度，次级标题会自动生成目录展示在页面上。默认情况下，这里填的是从 <h2> 到 <h4> ，也就是有三级深度。当然，你也可以根据需要自由选择，比如，“没有目录”（不显示目录，如登陆页），或者“所有级别”。
-
最大渲染时长
-
确定页面自动刷新的频率。在绝大多数情况下，设置为零。
-
查找
-
对于已本地化的页面，这个字段可以帮助重新关联变成“孤儿”的页面（脱离英文原版的页面）。对于英语页面来讲，这个字段用处不大，因为，英语是 MDN 的官方语言。
-
- -

新页面

- -

如果你拥有创建页面权限，你就可以创建新的页面了。查看如何创建和编辑页面你可以了解到更多这方面的知识。对于创建新页面，页面信息区域看起来如下图：

- -

Page info fields for a new page

- -

你同样可以设置标题和目录，还可以设置页面的别名，别名用于页面URL地址的最后一个部分。以只读状态显示的父地址是页面URL中网站根节点之后的部分。当你在标题输入框中输入文字的时候，别名输入框会自动生成对应的内容，其中会用下划线替代标题中的空格。

- -
-

值得注意的是，我们推荐使用更短的别名和描述更清晰的标题。举例来说，一个关于编辑器页面控件的页面，应该取一个例如：“MDN 编辑器页面控件”的标题，而它的 URL 应该写成“MDN/Contribute/Editor/Basics/Page_controls”，其中“Page_controls”正是这个页面的别名。

-
- -

 

diff --git a/files/zh-cn/mdn/editor/edit_box/index.html b/files/zh-cn/mdn/editor/edit_box/index.html deleted file mode 100644 index de23593df5..0000000000 --- a/files/zh-cn/mdn/editor/edit_box/index.html +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: MDN 编辑器的编辑框 -slug: MDN/Editor/Edit_box -tags: - - MDN - - 快捷键 - - 编辑器 - - 编辑框 -translation_of: MDN/Editor/Keyboard_shortcuts ---- -

编辑框正是你写文章的地方，在编辑框中点击右键会根据你点击的位置打开对应的快捷菜单，比如：在表格中点击右键会弹出与编辑表格相关的菜单，在列表中右击就会弹出与列表相关的菜单。

- -

默认情况下，编辑器会用自己的右键菜单替代浏览器默认的菜单，如果你一定要打开浏览器的默认菜单（比如，使用火狐的拼写检查功能），你可以按住 Shift 或 Control 键（ Mac 的 Command 键），再点击右键。

- -

快捷键

- -

丰富而便捷的键盘快捷键能让你在编辑时，手不离开键盘。此处所列的是 Windows 或 Linux 系统下的快捷键，如果是 Mac，只需将 Control 替换为 Command 即可。

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
快捷键描述
Ctrl + A全选
Ctrl + C复制
Ctrl + V粘贴
Ctrl + Shift + V粘贴为纯文本
Ctrl + X剪切
Ctrl + Z撤销
Ctrl + Y重做
Ctrl + K打开链接编辑器/添加新链接
Ctrl + Shift + K移除光标所在位置的链接
Ctrl + B加粗
Ctrl + I斜体
Ctrl + O切换 <code> 样式
Ctrl + Shift + O -

切换源码编辑模式

- -
使用源码编辑模式时请格外小心，你必须按照既定的格式来编辑。请仔细阅读编辑器源码模式指南，该指南详细介绍了如何使用源码模式，以及各项注意事项。
-
Ctrl + P切换当前区域的 <pre> 样式
Ctrl + U下划线
Ctrl + S保存但不关闭编辑器
Ctrl + Shift + S保存并关闭编辑器
Ctrl + 0移除选中区域的样式（此处是数字“0”，不是字母“O”）
Ctrl + 2  至  Ctrl + 6切换标题的级别（从 2 到 6 ），一级标题仅可供文章头部的页面标题使用。
Ctrl + Shift + L在无序列表、有序列表和普通段落格式之间切换。
Tab在缩进模式下增加缩进级别，否则插入两个空格作为制表符。在表格内部，将光标移动到下一个单元格，或者在没有下一个单元格的情况下插入新行。如果光标当前位于页面标题或某个标题中，则光标跳转到下一段。
Shift + Tab在缩进模式下降低缩进水平。在表格内部，跳到前一个单元格，如果前面没有单元格，则插入新行。如果光标当前位于页面标题或某个标题中，则光标跳转到下一段。
Shift + Space插入空格(&nbsp;)
Shift + Enter -

跳出当前区域。例如，如果你当前正在某个 <pre> 区域，按下 Shift + Enter ，你将跳出这个区域，回到文章正文。

- -
-

当前不可用，详见：{{bug('780055')}}。

-
-
- -

参阅

- - - -
{{MDNSidebar}}
diff --git a/files/zh-cn/mdn/editor/index.html b/files/zh-cn/mdn/editor/index.html deleted file mode 100644 index 02f71ade9f..0000000000 --- a/files/zh-cn/mdn/editor/index.html +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: MDN 编辑指南 -slug: MDN/Editor -tags: - - MDN - - 指南 - - 文档 -translation_of: MDN/Editor ---- -
{{MDNSidebar}}
- -
{{IncludeSubnav("/zh-CN/docs/MDN")}}
- -

MDN Web Docs wiki 文档系统的 WYSIWYG (所见即所得)编辑器让贡献新的内容变得简单。这篇指南将告诉你如何使用它，借此来提高你的生产力。在编辑或新建新的页面之前，请阅读并遵守 Mozilla 条款。

- -

MDN 样式指南 除了告诉你如何进行格式化和样式化内容本身外，还包括我们推荐的语法和拼写规则。

- -

{{LandingPageListSubpages}}

- -

{{EditorGuideQuicklinks}}

diff --git a/files/zh-cn/mdn/editor/source_mode/index.html b/files/zh-cn/mdn/editor/source_mode/index.html deleted file mode 100644 index 660f88267e..0000000000 --- a/files/zh-cn/mdn/editor/source_mode/index.html +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: 源码模式 -slug: MDN/Editor/Source_mode -translation_of: MDN/Editor/Source_mode ---- -
{{MDNSidebar}}
- -

MDN 编辑器有个重要的按键，用来切换到源码编辑模式。此模式下，你可以看到正在编辑的文章的 HTML。这个指引使你了解 MDN wiki 源码编辑模式能做什么，什么应该做，但更为重要的是，什么是不应该做的。

- -
-

在你考虑使用源码模式之前，请注意我们强烈建议你不要使用源码模式。如果您只是为了强行符合我们的样式规范，你不应该去使用源码模式。我们确实有一些需求不启用源码模式无法做到。记得查看{{anch("Warnings and caveats")}}。

-
- -

启用源码模式

- -

启用源码模式很简单。在编辑器工具栏的左上角，点击“Source”或“原始碼”按钮。

- -

Partial screenshot of the editor toolbar, with the Source mode button highlighted

- -

对于格式化、图片之类的功能，很可能源码模式没有 WYSIWYG (所见即所得)好用，因为你可能需要滚动很远才能找到编辑器中相关源码的位置。

- -

警告

- -

综上所述，你应该极少会需要用到源码模式。只有一些极个别的事情才必须由修改源码实现。最终，我们会更新编辑器界面，为你展示你的修改。

- -

MDN贡献者指南中未明确描述的所有内容均不应添加到源代码中。这意味着：

- - - -

源码模式下编辑

- -

一旦启用源码模式，你将可以编辑 wiki 页面的原始 HTML。虽不受编辑器约束，您应竭尽所能保持您的工作与样式指南一致，并且可以安全可靠的工作。

- -
-

通常，您应该是在源码模式中做一些短暂的调整，而不是长时间的撰写页面。

-
- -

不幸的是，Tab 键在源码模式中无法使用，请输入两个空格来代替。

- -

若您使用 MDN 不允许的 HTML 元素和属性，它们会在你保存时直接被移除。此外，文档还将重新被格式化，以使之符合预期。

- -

合理使用源码模式

- -

在一些个别的情况下，使用源码是唯一能遵循MDN格式规范的方式。这一节涵盖了这些情况，并说明了如何在不破坏其他东西的前提下，正确使用这些功能。

- -

在示例代码中高亮代码行

- -

在用工具栏的块组中的PRE或Syntax Highlighter建立的示例代码片段块中，你会希望让某几行代码更引人注目一些。唯一实现这种事项的方式是开启源码模式，找到包含此部分代码的{{HTMLElement("pre")}}块，然后编辑<pre>标签的{{htmlattrxref("class")}}属性，加上一个highlight组件，像下面这种格式：

- - - -

例如，如果现在的标签为<pre class="brush: js">，然后你想往第4行和第7行加个高亮，你可把它改为<pre class="brush:js; highlight:[4,7]">。

- -

我们看个更复杂的示例：

- - - - - - - - - - - - - - -
高亮前高亮后
- 
-var canvas = document.getElementById("canvas");
-var ctx = canvas.getContext("2d");
-
-var path1 = new Path2D();
-path1.rect(10, 10, 100, 100);
-
-var path2 = new Path2D(path1);
-path2.moveTo(220, 60);
-path2.arc(170, 60, 50, 0, 2 * Math.PI);
-
-ctx.stroke(path2);
-
- -

这里的{{HTMLElement("pre")}}标签为：<pre class="brush: js">

- 		- 
-var canvas = document.getElementById("canvas");
-var ctx = canvas.getContext("2d");
-
-var path1 = new Path2D();
-path1.rect(10, 10, 100, 100);
-
-var path2 = new Path2D(path1);
-path2.moveTo(220, 60);
-path2.arc(170, 60, 50, 0, 2 * Math.PI);
-
-ctx.stroke(path2);
- -

然后这里的<pre>标签已经改为了：<pre class="brush: js; highlight:[4,7]">

-
- -

没有对应工具栏按钮的样式

- -

MDN上我们用的一些样式通过通常的用户界面是无法实现的。好消息是，这些不是很常见。示例如：

- - diff --git a/files/zh-cn/mdn/guidelines/content_blocks/index.html b/files/zh-cn/mdn/guidelines/content_blocks/index.html deleted file mode 100644 index b2b145fe60..0000000000 --- a/files/zh-cn/mdn/guidelines/content_blocks/index.html +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: 内容块 -slug: MDN/Guidelines/Content_blocks -translation_of: MDN/Guidelines/CSS_style_guide -translation_of_original: MDN/Structures/Content_blocks ---- -
{{MDNSidebar}}
-

This pages lists reusable content blocks.

-
-

Card-grid

-

Allows to have a couple of cards next to each other to call out specific contents or can be used for a call to action. CSS class: .card-grid (L 751 - 824 in CustomCSS).

- -

Two columns

-

Two columns seperated with a thick grey border. Often used on landing pages. CSS class: .topicpage-table (L 830 - 837 & 82-93 in CustomCSS).

-
-
- Column 1
-
- Column 2
-
-

 

-

Equal column heights

-

Used on the Firefox OS landing page to wrap columns that should all be the same height. CSS class .equalColumnHeights (L 25 - 38 in CustomCSS).

-
-
- Some text
- And a new line
-  
-
- Some more text
-
-
- here
-
-

 

diff --git a/files/zh-cn/mdn/guidelines/does_this_belong_on_mdn/index.html b/files/zh-cn/mdn/guidelines/does_this_belong_on_mdn/index.html new file mode 100644 index 0000000000..1f40cc49b8 --- /dev/null +++ b/files/zh-cn/mdn/guidelines/does_this_belong_on_mdn/index.html @@ -0,0 +1,193 @@ +--- +title: MDN收录规则 +slug: MDN/Guidelines/Rules_Of_MDN_Documenting +translation_of: MDN/Guidelines/Does_this_belong_on_MDN +--- +
{{MDNSidebar}}
{{IncludeSubnav("/zh-CN/docs/MDN")}}
+ +

如果你正准备记录什么信息，你可能想知道是否要将这些信息放入MDN。 更进一步地，你可能想在你的源代码中维护文档，并将文档写入Mozilla wiki，或者写入某Git仓库的readme文件中。 本文的目的是帮助你确认你的内容是否适合MDN。

+ +

文档是否应放入MDN主要取决于两点：

+ + + +
+

注意Mozilla的 Websites & Communications Terms of Use 所声明的条例在你使用MDN或对其做贡献时是生效的。检查这个文档，确保你知道在Mozilla的网站上什么是能发表的，什么是不能发表的。

+
+ +

哪些话题在MDN的范畴内？

+ +

MDN涉及了惊人的各种材料。总的来说，如果它是开放的面向Web的技术，或者是Mozilla的产品，我们就把它收录到MDN。但也有一小部分东西完全不属于MDN。这一节会告诉你如何确认你的文档是否属于MDN。

+ +

这里有一些我们涉及的事物；虽然这不是一个完整的列表，但是可以给你一个大致的印象。

+ +

开放的Web标准与技术

+ +

现在Web标准文档中受关注的是那些可以被Web开发者用于创建网站与App这些大众应用的功能。这指的是那些被众多浏览器所实现，要么是被标准接受，要么是正在向标准化发展的技术。即主要关注前端Web技术。后端的技术常常在别处有它们自己的文档，MDN不会去尝试取代它们。

+ + + +

同时欢迎关注与Web开发有关的交互技术话题，比如：

+ + + +
+

注意： MDN 涉及了非Mozilla但对Web开放的技术；举个例子，我们有关于WebKit格式的CSS属性的文档。

+
+ +

Mozilla 产品

+ +

这个分类的文档包括如何作为开发者使用Mozilla的产品，以及如何向这些开源项目贡献。

+ + + +

哪些话题不属于MDN？

+ +

举一些不适合MDN的话题：

+ + + +

哪些类型在MDN的范畴内？

+ +

In general, MDN is for product documentation, not for project or process documentation (except about MDN itself). So, if the document is about "how to use a thing" or "how a thing works" (where the "thing" is in one of the topic categories mentioned above), then it can go on MDN. But if it about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN. In that case, if the thing is being developed under the umbrella of Mozilla, then the Mozilla project wiki may be a good place for it.

+ +

Here are some examples of types of documents that should not be placed on MDN:

+ + + +

Advantages to documenting on MDN

+ +

If you've determined that the documentation you want to write is appropriate in content and type for MDN, but you're still not sure whether MDN is the best place for it, read on.  There are a lot of good reasons to create documentation on MDN.

+ +

Lots of writers and translators

+ +

The MDN community is big. Really big. It's big in the sort of way that makes big things look small. Seriously, we have a lot of people that participate in creating and maintaining content on MDN. With writers and editors on every continent (okay, I'm not sure about Antarctica, but otherwise), there's a lot of value to the sheer volume of writers:

+ + + +

Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.

+ +

维护

+ +

Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:

+ +
+
Delete spam
+
Spam happens. We deal with it.
+
Copy editing
+
You don't have to worry if your writing isn't as clear or precise as you'd like. We'll turn your prose into something other people can read.
+
Consistency of style
+
We'll ensure that your content is stylistically consistent not just within itself, but with the other documentation around it.
+
Content management
+
Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.
+
Site and platform maintenance
+
MDN has both an IT team who keep the site up, running, and secure, and a platform development team who maintain and enhance the platform. You won't need to devote your own or additional resources to documentation infrastructure.
+
+ +

Cases for documenting elsewhere

+ +

There are also a few reasons you may be thinking about documenting your work somewhere other than MDN. Here are some of those reasons, and the pros and cons for each.

+ +

Plans and processes

+ +

Documentation for plans, processes, and proposals should never be put on MDN. That's pretty simple. If your project is part of Mozilla, you can put them on the Mozilla project wiki.

+ +

The project is on Github

+ +

Some of Mozilla's projects are hosted on Github, and Github offers its own wiki-like system for documentation. Some teams like to produce their documentation there. This is certainly fair and convenient if you're game to write your own docs; however, keep in mind that:

+ + + +

It's possible, of course, that these things don't bother you, or aren't a problem in your situation. Some teams don't mind keeping their own docs, or are working on code that has minimal documentation needs.

+ +

You want to keep docs in-source

+ +

Some teams like to have their documentation in the source tree. This is particularly common with project internals and library projects.

+ +

This approach has a couple of advantages:

+ + + +

There are some drawbacks:

+ + + +

Still, this can be a viable option (possibly even a good option) for some types of projects, especially small ones or those that aren't expected to get much interest.

+ +

{{endnote("*")}} It's OK to put a limited amount of personal information on your MDN profile page. User profiles should reflect a human being, not a business or organization. A moderate degree of self-promotion is OK, but link-spamming is not. Please do not use your profile to upload personal photos or other irrelevant files.

diff --git a/files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html b/files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html deleted file mode 100644 index 1f40cc49b8..0000000000 --- a/files/zh-cn/mdn/guidelines/rules_of_mdn_documenting/index.html +++ /dev/null @@ -1,193 +0,0 @@ ---- -title: MDN收录规则 -slug: MDN/Guidelines/Rules_Of_MDN_Documenting -translation_of: MDN/Guidelines/Does_this_belong_on_MDN ---- -
{{MDNSidebar}}
{{IncludeSubnav("/zh-CN/docs/MDN")}}
- -

如果你正准备记录什么信息，你可能想知道是否要将这些信息放入MDN。 更进一步地，你可能想在你的源代码中维护文档，并将文档写入Mozilla wiki，或者写入某Git仓库的readme文件中。 本文的目的是帮助你确认你的内容是否适合MDN。

- -

文档是否应放入MDN主要取决于两点：

- - - -
-

注意Mozilla的 Websites & Communications Terms of Use 所声明的条例在你使用MDN或对其做贡献时是生效的。检查这个文档，确保你知道在Mozilla的网站上什么是能发表的，什么是不能发表的。

-
- -

哪些话题在MDN的范畴内？

- -

MDN涉及了惊人的各种材料。总的来说，如果它是开放的面向Web的技术，或者是Mozilla的产品，我们就把它收录到MDN。但也有一小部分东西完全不属于MDN。这一节会告诉你如何确认你的文档是否属于MDN。

- -

这里有一些我们涉及的事物；虽然这不是一个完整的列表，但是可以给你一个大致的印象。

- -

开放的Web标准与技术

- -

现在Web标准文档中受关注的是那些可以被Web开发者用于创建网站与App这些大众应用的功能。这指的是那些被众多浏览器所实现，要么是被标准接受，要么是正在向标准化发展的技术。即主要关注前端Web技术。后端的技术常常在别处有它们自己的文档，MDN不会去尝试取代它们。

- - - -

同时欢迎关注与Web开发有关的交互技术话题，比如：

- - - -
-

注意： MDN 涉及了非Mozilla但对Web开放的技术；举个例子，我们有关于WebKit格式的CSS属性的文档。

-
- -

Mozilla 产品

- -

这个分类的文档包括如何作为开发者使用Mozilla的产品，以及如何向这些开源项目贡献。

- - - -

哪些话题不属于MDN？

- -

举一些不适合MDN的话题：

- - - -

哪些类型在MDN的范畴内？

- -

In general, MDN is for product documentation, not for project or process documentation (except about MDN itself). So, if the document is about "how to use a thing" or "how a thing works" (where the "thing" is in one of the topic categories mentioned above), then it can go on MDN. But if it about "who's working on developing a thing" or "plans for developing a thing", then it shouldn't go on MDN. In that case, if the thing is being developed under the umbrella of Mozilla, then the Mozilla project wiki may be a good place for it.

- -

Here are some examples of types of documents that should not be placed on MDN:

- - - -

Advantages to documenting on MDN

- -

If you've determined that the documentation you want to write is appropriate in content and type for MDN, but you're still not sure whether MDN is the best place for it, read on.  There are a lot of good reasons to create documentation on MDN.

- -

Lots of writers and translators

- -

The MDN community is big. Really big. It's big in the sort of way that makes big things look small. Seriously, we have a lot of people that participate in creating and maintaining content on MDN. With writers and editors on every continent (okay, I'm not sure about Antarctica, but otherwise), there's a lot of value to the sheer volume of writers:

- - - -

Do you want your development team to be entirely responsible for the production of documentation? That's likely if your documentation is maintained elsewhere.

- -

维护

- -

Because of the sheer number of contributors, there's usually someone on hand to watch for problems with your content: from spam control to copy-editing, things can happen around the clock. Here's just a taste of what our team can do:

- -
-
Delete spam
-
Spam happens. We deal with it.
-
Copy editing
-
You don't have to worry if your writing isn't as clear or precise as you'd like. We'll turn your prose into something other people can read.
-
Consistency of style
-
We'll ensure that your content is stylistically consistent not just within itself, but with the other documentation around it.
-
Content management
-
Our team will help ensure that the documentation is cross-linked with other relevant materials, that articles are put in the right places, and that menus and other infrastructure is built to make it easy to follow and understand.
-
Site and platform maintenance
-
MDN has both an IT team who keep the site up, running, and secure, and a platform development team who maintain and enhance the platform. You won't need to devote your own or additional resources to documentation infrastructure.
-
- -

Cases for documenting elsewhere

- -

There are also a few reasons you may be thinking about documenting your work somewhere other than MDN. Here are some of those reasons, and the pros and cons for each.

- -

Plans and processes

- -

Documentation for plans, processes, and proposals should never be put on MDN. That's pretty simple. If your project is part of Mozilla, you can put them on the Mozilla project wiki.

- -

The project is on Github

- -

Some of Mozilla's projects are hosted on Github, and Github offers its own wiki-like system for documentation. Some teams like to produce their documentation there. This is certainly fair and convenient if you're game to write your own docs; however, keep in mind that:

- - - -

It's possible, of course, that these things don't bother you, or aren't a problem in your situation. Some teams don't mind keeping their own docs, or are working on code that has minimal documentation needs.

- -

You want to keep docs in-source

- -

Some teams like to have their documentation in the source tree. This is particularly common with project internals and library projects.

- -

This approach has a couple of advantages:

- - - -

There are some drawbacks:

- - - -

Still, this can be a viable option (possibly even a good option) for some types of projects, especially small ones or those that aren't expected to get much interest.

- -

{{endnote("*")}} It's OK to put a limited amount of personal information on your MDN profile page. User profiles should reflect a human being, not a business or organization. A moderate degree of self-promotion is OK, but link-spamming is not. Please do not use your profile to upload personal photos or other irrelevant files.

diff --git a/files/zh-cn/mdn/guidelines/style_guide/index.html b/files/zh-cn/mdn/guidelines/style_guide/index.html deleted file mode 100644 index 285b2703cb..0000000000 --- a/files/zh-cn/mdn/guidelines/style_guide/index.html +++ /dev/null @@ -1,784 +0,0 @@ ---- -title: MDN Web 文档写作规范 -slug: MDN/Guidelines/Style_guide -tags: - - MDN - - MDN Meta - - MDN Web 文档 - - MDN 规范 - - 写作规范 - - 准则 - - 教程 - - 文档 - - 规范 -translation_of: MDN/Guidelines/Writing_style_guide ---- -
{{MDNSidebar}}
- -

{{IncludeSubnav("/zh-CN/docs/MDN")}}

- -

为了提供更加组织化、标准化且易于阅读的文档，MDN Web 文档写作规范明确了文本的组织方式、拼写规则、固定格式等内容，不过这些内容只是指导性的而不是严格的规定，因为比起格式我们对内容更感兴趣，所以没有必要在参与贡献之前强迫自己学习本规范。但是如果有一位勤劳的志愿者在之后编辑了你的文档使它更加符合本规范，也请不要感到惊讶或难过。

- -

如果你正在寻找一个特定类型的页面应该如何构建的相关细节，请参阅MDN Web 文档页面布局规范。

- -

本规范主要适用于英文文档。 其他语言可能也有（也欢迎创建）相应的规范。 这些应该作为子页面发布在各个本地化小组的页面中。

- -
-

译注：本文的写作规范虽说是针对英文所写，但是其中的不少内容也适用于中文，可花点时间阅读一下。另外，中文翻译时的规范请参见《翻译术语表和翻译规范》。

-
- -

对于那些为MDN以外的站点内容所编写的规范，请参考 Mozilla 统一规范。

- -

基础部分

- -

为了使文档保持更好的一致性，所有主流的写作规范指南都是从一些比较基本的写作规范开始的。以下几个小节所概述的这些基本规范内容应该会对你有很大帮助。

- -

页面标题

- -

页面标题不仅会在搜索时用到，在页面顶部的面包屑路径中也会被用来表示文档的层级结构。页面标题（就是显示在页面顶部以及搜索结果中标题的部分）可以与页面URL“<locale>/docs/”之后的“铭牌（slug）”部分不同.

- -

文章标题和段落标题的大写规则

- -

页面的标题和章节的标头应当使用语句式大写（只大写第一个单词的首字母以及专有名词的首字母），而不应该使用标题式大写：

- - - -

我们还有很多旧的页面是在这条规范确立之前就已经发布了的。所以只要你愿意，你随时可以更新它们的标题。我们也正在逐步完善它们。

- -

标题和铭牌的选择

- -

页面的铭牌应该尽量简短，当创建一个新的层级时，新层级的铭牌最好只由一到两个单词组成。

- -

而页面的标题长度并没有什么严格的限制，只要合理并且表意明确即可。

- -

创建新的子目录

- -

当你要给某个新的主题或主体添加文章时，你通常需要创建一个引导页，然后再把要添加的文章作为子页面添加进去。引导页开篇应当用一两段话来描述一下当前主题或技术，然后添加一个子页面的目录列表，并简要描述每个页面的内容。你可以使用一些我们已经编写好的宏把相关的子页面自动插入到目录列表中。

- -

例如，JavaScript手册,其结构如下：

- - - -

尽量避免把文章内容放置在层次结构的顶层，这会降低网站的访问速度，同时搜索和导航的效率也会下降。

- -

文章内容的通用原则

- -

在写任何文档时，知道该写多少是很重要的。如果你写的长篇大论，文章读起来就会冗长无味,更不会有人愿意使用它。保持文章内容适量很重要,原因有很多。这其中的原因就有：为了确保读者能够找到他们真正想要的信息，以及为搜索引擎提供足够的优质素材来对文章进行分析和排名。我们将在这里讨论前者（提供读者可能需要的信息）。如果想了解如何让文章更好地被搜索引擎分类和排名，查阅文章How to write for SEO on MDN。

- -

我们的目标是在页面中包含读者可能需要的所有信息，但又不至于太过冗长。为了实现这个目标,我们给出了一些建议。

- -

为读者着想

- -

请记住，这些只是指导性的。其中某些建议并不适用于所有状况。当然你应该始终为你的读者着想。例如，在一篇介绍高级网络技术的文章中，通常不需要像介绍网络编程的文章那样包含过多的网络基本概念。

- -

提供一个有用的简介

- -

在开篇或第一个段落标题之前给出文章的简介，以使读者快速了解文章中是否包含他们感兴趣的内容。在指南或教程类的文章中，简介还应该让读者明白文章覆盖了哪些主题，以及文章期望读者能够从中了解到哪些知识。简介中应该包含文章中介绍和讨论的技术、API，并提供相关的链接，同时还应该提供可能会遇到的情况的提示。

- -
示例：过于简短的简介
- -

下面这个例子中的简介太过于简短，很多信息都没有包含进来，比如“stroke text”是什么意思，文本会在哪里等。

- -
-

CanvasRenderingContext2D.strokeText() draws a string.

-
- -
示例：过于冗长的简介
- -

下面是上面那个简介的修改版，但是这次它又太过冗长了。其中包含了过多的细节，并且还包含了很多其他方法和属性，但实际上它应该将重点聚焦在 strokeText() 方法上，然后给出详细介绍它的文章的链接即可。

- -
-

译注：作为例子，内容并不重要，所以就不逐句翻译了。

-
- -
-

When called, the Canvas 2D API method CanvasRenderingContext2D.strokeText()strokes the characters in the specified string beginning at the coordinates specified, using the current pen color. In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.

- -

The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.

- -

The placement of the text relative to the specified coordinates are determined by the context's textAlign, textBaseline, and direction properties. textAlign controls the placement of the string relative to the X coordinate specified; if the value is "center", then the string is drawn starting at x - (stringWidth / 2), placing the specified X-coordinate in the middle of the string. If the value is "left", the string is drawn starting at the specified value of x. And if textAlign is "right", the text is drawn such that it ends at the specified X-coordinate.

- -

(etc etc etc...)

- -

You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.

- -

You can call the fillText() method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.

-
- -
示例：这次好多了
- -

下面这个简介比前两个要好很多。

- -
-

The {{domxref("CanvasRenderingContext2D")}} method strokeText(), part of the Canvas 2D API, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.

- -

For more details and further examples, see {{SectionOnPage("/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, Drawing text.

-
- -

多提供一些示例

- -

文章应该尽量多提供一些示例。实际上，大多数文章都应该包含不止一个例子。使用例子来说明每个参数的用途或每个可能的边界条件是很有必要的。同时还应该用例子来演示常见问题的解决方法，以及应该如何解决使用过程中可能碰到的坑。

- -

每个例子都应该先给出解释，说明它做了什么，以及读者在阅读或动手尝试之前需要了解的内容。

- -

另外，每段示例代码都应该就其工作原理给出说明。最好将一段较长的代码分解成多个较小的部分，并提供每个部分的说明，说明时注意细节的层次。如果代码很简单并且不直接涉及到当前 API，可以只给出一个简单的介绍，说明其用途，以及为何要把它放在这里；而如果代码比较复杂、或用到了当前的 API、或在技术上比较有创造性，那么你应该提供更详细的说明。

- -

如果使用的是在线演示的方式，则可以将 HTML、CSS、JavaScript 拆分到不同的 {{HTMLElement("pre")}} 中，它们在运行时会自动组合到一起，但使用这种方式每个里面都可以有自己的说明。因此这是一种很好很强大的方式。

- -

过短的文章难以被搜索到

- -

如果文章过短，那么搜索引擎可能会难以甚至无法对其建立关键字索引。一般来说，文章的主体内容应该至少包含 250-300 个单词。但是也不要对内容确实很少的文章进行刻意的扩充，在可能的情况下尽量遵守该指导原则即可。

- -

小节、段落和换行

- -

对于小节的标题，应使用从大到小的方式来定义级别：{{HTMLElement("h2")}}、{{HTMLElement("h3")}}、{{HTMLElement("h4")}} 这样，并且中间不要跳过某一级。因为 H1 已用于文章的标题，因此小节的标题应该从 H2 开始。如果你的文章中小节的层次超过了 3 到 4 级，那么你可能需要考虑将整篇文章拆分成几篇小的文章，然后用一个引导页给出这些文章的链接，并用 {{TemplateLink("Next")}}、{{TemplateLink("Previous")}}、{{TemplateLink("PreviousNext")}} 宏为它们创建导航。

- -

按下回车键（Enter 或 Return）可以开始一个新的段落。如果只是想换行而不是另起一段，可以按住 Shift 并敲下回车。

- -

不要创建只包含一个小节的子级别，如果只有一个小节，那么拆分主题就是没有意义的。至少包含两个小节，要么就不要拆分。

- -

不要让两个小节标题紧挨在一起，这样看起来很丑。每个小节标题的下面至少要放上一段对后面各子小节的简短说明，这会对阅读的人很有帮助。

- -

列表

- -

列表的格式应该在所有文章中保持一致，并且应在列表中恰当使用标点和结构合理的句子。不管是哪种类型的列表，都需要对格式进行适当的调整。下面的内容说明了每种列表之间的不同。

- -

无序列表

- -

无序列表可以以简洁且有效的方式对内容进行分组显示。每个条目都会以类似“•”的符号来标识。在无序列表中要注意正确使用标点，尤其是每句的最后不要遗漏掉句号。应该以标准写作方式来对待无序列表。

- -

下面是一个结构良好的无序列表的例子：

- -
-

在这个例子中需要包括:

- - -
- -

可以看到，每个条目的格式都是一致的：首先显示一个“•”符号，然后列出一种情况，然后写上逗号，并在逗号后面添加一些对当前情况的简单说明。

- -

有序列表

- -

有序列表用序号来标识每个条目。同样要注意应该在有序列表中使用适当的格式，保持列表的清晰和简洁，这一点与无序列表是类似的。但是有序列表中的某些条目内容可能会很多，因此正确使用标点就更为重要了，因为难免会遇到必须使用复杂句子的情况。

- -

下面是一个结构良好的有序列表的例子：

- -
-

为了创建一个好的有序列表，你需要：

- -
    -
  1. 以一个介绍性的标题开始，以引出后续的序列。我们可以在开始有序列表的序列之前提供这一内容。
    2. -
  2. 开始创建各个序列，这些序列会用数字依次编号。这是有序列表的标准格式，能够很容易地被读者理解。有序列表中的某些条目内容可能会很多，因此正确使用标点是很重要的。
    3. -
  3. 列表序列完成之后，应在后面再提供一段简短的总结。
    4. -
- -

这段内容就是一个总结。我们已经创建了一个简短的有序列表，解释了创建良好格式的有序列表应遵循的步骤。

-
- -

有序列表基本都用来表示具有连续性关系的内容，因此应该先深入思考你要用这些内容达到什么目的，然后再去撰写。

- -

文本格式和样式

- -

可以使用“样式”下拉列表中的预定义样式来格式化你选定的内容。

- -
-

“Note”样式用来强调重要提示，就像这个。

-
- -
-

类似地，“Warning”样式用来创建一个警告框。

-
- -

除非有特殊需要，否则请不要用 HTML 的 style 属性来手动给内容添加样式。如果你没有找到你需要的预定义样式，可以放置一个 {{IRCLink("mdn")}} 并寻求帮助。

- -

示例代码的格式和样式

- -
-

这一小节只是讨论 MDN 文章中的示例代码的样式和格式问题，如果你想了解如何编写示例代码，请参考示例代码指南。

-
- -

缩进和换行符

- -

每级缩进都使用两个空格来缩进，并在所有的示例中保持一致。对于代码块的起始语句，应将开大括号“{”与当前语句写在一行上，比如：

- -
if (condition) {
-  /* handle the condition */
-} else {
-  /* handle the "else" case */
-}
-
- -

如果一行的代码很长，应在适当的地方换行以避免出现水平滚动条。下面是一个例子：

- -
if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
-       || class.YET_ANOTHER_CONDITION ) {
-  /* something */
-}
-
-var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
-                           .createInstance(Components.interfaces.nsIToolkitProfileService);
-
- -

内联代码格式

- -

对于函数名、变量名、方法名等，应使用“Inline Code”按钮（编辑器中显示为“<>”的按钮）将其设置为内联代码格式（内联代码使用的是 {{HTMLElement("code")}} 元素）。比如：frenchText() 函数。

- -

方法名后面应该加上小括号：doSomethingUseful()，这样会比较容易将方法与其他代码元素区分开来。

- -

语法高亮

- -

Screenshot of the 'Syntax Highlighter' menu.对于整行或多行代码，此时别再使用 {{HTMLElement("code")}}  元素来格式化了，而应该对其进行语法高亮。点击语法高亮器按钮（图标是两个代码块），从语言下拉列表中选择一种合适的语言即可。见右图。

- -

下面的例子使用了 JavaScript 语法高亮：

- -
-
for (var i = 0, j = 9; i <= 9; i++, j--)
-  document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);
-
- -

如果没有在下拉列表中找到你需要的语言，可以选择第一项“没有高亮”，此时代码显示的是不带高亮效果的普通样式：

- -
x = 42;
- -

语法定义

- -

如果你想插入一段语法定义，可以使用样式下拉列表中的“Syntax Box”选项。语法定义的样式与普通代码的样式会有所区别。

- -

非代码区块

- -

有些情况下需要用到 <pre> 区块而不是代码区块，此时不会进行语法高亮，也不会显示行号。比如你需要显示树形结构，就可以使用 <pre>：

- -
root/
-
-    folder1/
-        file1
-
-    folder2/
-        file2
-        file3
-
- -

插入方法是要先点击”pre“按钮，然后输入想要的内容即可。

- -

HTML 元素的样式

- -

HTML 元素的样式有一套自己的规则。遵守这些规则可以让元素及其组件的描述方式保持统一，并且还可以保证能够正确链接到各元素的详细文档页面。

- -
-
元素名称
-
使用 {{TemplateLink("HTMLElement")}} 宏会生成一个指向该元素详情页的链接。比如，\{{HTMLElement("title")}} 会生成”{{HTMLElement("title")}}“。如果不想生成链接，就将元素名称用尖括号括起来，然后将其设置为内联代码样式，比如 <title>。
-
属性名称
-
请使用粗体。
-
属性定义
-
对正在定义的术语使用 {{TemplateLink("htmlattrdef")}} 宏（如 \{{htmlattrdef("type")}}），这样其他页面就可以使用 {{TemplateLink("htmlattrxref")}} 宏来链接到该页面了（例如 \{{htmlattrxref("attr","属性")}}）。
-
属性值
-
请使用内联代码样式，并且注意字符串两边不要加引号，除非是代码的语法要求加引号。举例：当将 <input> 元素的 type 属性设置为 email 或 tel 时……
-
为属性添加说明标签
-
请不要滥用 {{HTMLVersionInline(5)}} 这样的标签。比如，可以在某个第一次出现的属性名称旁边添加标签，但是不要在每次出现该属性的时候都添加一次。
-
- -

拉丁文缩写

- -

在补充说明的括号中

- -

一般的拉丁文缩写（如：”etc.“、”i.e.“、”e.g.“）都可以用在起补充说明的括号里面。这时应在缩写中添加句号，后面加上逗号或其他恰当的标点。

- - - -

在一般句子中

- -

在普通的句子中（即括号的外面），请使用与缩写等价的英文单词或短语。

- - - -

缩写、拉丁文原文和英文的对照表

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
缩写拉丁文英文
cf.confercompare
e.g.exempli gratiafor example
et al.et aliiand others
etc.et ceteraand so forth, and so on
i.e.id estthat is, in other words
N.B.nota benenote well
P.S.post scriptumpostscript
- -
-

在使用前请仔细思考使用拉丁文缩写是否真的能带来好处。上面列出的某些缩写很少用到，很多读者可能不知道其意思，还有一些读者可能会分不清其中的某些缩写。另外，如果你决定使用缩写，那么请确保你的用法是正确的。比如，一个很多人经常会犯的错误是将“e.g.”和“i.e.”弄混。

-
- -

首字母缩写和一般缩写

- -
-
大写与句号
-
在这两种缩写中（包括国家和组织的缩写，如“US”、“UN”），请使用全大写且不要添加句号。
-
-
    -
  • 正确: XUL
    • -
  • 错误: X.U.L.、Xul
    • -
-
-
缩写展开
-
文章中第一次遇到某个缩写术语时，应该同时给出其展开形式，从而让不了解该缩写的读者能够知道它所指代的内容。如果不确定要不要展开那么就选择展开，或者更好的办法是将其链接到术语表中的对应条目。
-
-
    -
  • 正确: XUL (XML User Interface Language) is Mozilla's XML-based language...
    • -
  • 错误: XUL is Mozilla's XML-based language...
    • -
-
-
缩写的复数形式
-
当需要使用复数形式的缩写时，直接在后面加上“s”即可，请务必不要加撇号。
-
-
    -
  • 正确: CD-ROMs
    • -
  • 错误: CD-ROM's
    • -
-
-
”Versus“、”vs.“和”v.“
-
推荐使用”vs.“。
-
-
    -
  • 正确: this vs. that
    • -
  • 错误: this v. that
    • -
  • 错误: this versus that
    • -
-
-
- -

大写

- -

在文章内容中请使用标准英文大写规则，比如对于”World Wide Web“需大写每个单词的首字母。如果”web“和”internet“是单独使用或作为修饰词使用，那么将其全小写也可以——这一指导原则是后来修改过的，所以在 MDN 中你也许会看到很多首字母大写的”Web“和”Internet“。当你编辑文章的时候遇到这种情况，可以随它去，也可以随手修改一下。但是仅仅只是为了修改一下大写的话就没必要专门去编辑一下了。

- -

对于键盘按键，应该使用普通的大写规则，而不是全大写。比如，是”Enter“而不是”ENTER“。

- -

简写

- -

我们倾向于宽松的写作风格，所以你可以按你的喜好来决定是否使用简写（如”don't“、”can't“、”shouldn't“）。

- -

名称复数

- -

请使用英文风格的复数形式，不要使用拉丁文或希腊文的形式。

- -
-
-
    -
  • 正确: syllabuses、octopuses
    • -
  • 错误: syllabi、octopi
    • -
-
-
- -

连字符

- -

当两个单词连起来组成另一个单词时，如果前一个单词的最后一个字母是元音字母，并且与后一个单词的第一个字母相同时，应使用连字符。

- -
-
-
    -
  • 正确: email、re-elect、co-op
    • -
  • 错误: e-mail、reelect、coop
    • -
-
-
- -

使用性别中立的表述

- -

在任何性别无关的场合使用性别中立的表述方式是一种比较好的做法，这样可以使你的文章具有普适性。举个例子，如果你正在写的是关于某个男人的行为，那么使用”他“来指代是没问题的；但如果内容并没有特指是男还是女，那么再使用”他“就不太恰当了。

- -

让我们再看几个例子：

- -

弹出一个对话框，让用户确认他是否允许网页使用他的网络摄像头。

- -

弹出一个对话框，让用户确认她是否允许网页使用她的网络摄像头。

- -

这两句话使用的都是特定性别的表述方式，我们可以将其修改为性别中立的代词：

- -

弹出一个对话框，让用户确认他们是否允许网页使用他们的网络摄像头。

- -
-

译注：这里原文为”they“和”their“，在英文中是性别中立的代词。而中文中如果上下文没有强调性别，则”他们“也具有性别中立性。

-
- -
-

MDN 允许使用这种通用性的语法（尽管在正式用法中这一点还存在争议）来弥补英语在表达中立性别时的不足。将第三人称复数的代词用来表示性别中立代词（即使用”they“、”them“、”their“、”theirs“）是可以接受的，也就是通常所说的”单数形式的‘they’“。

-
- -

你还可以同时写上两个性别：

- -

弹出一个对话框，让用户确认他或她是否允许网页使用他/她的网络摄像头。

- -
-

译注：中文里一般不这么用，所以如果在翻译中遇到这种情况，请简单翻译为”他“即可。”中文翻译规范“一文的”误解：100% 翻译 = 准确“一节中也提到了这个问题。

-
- -

或者使用复数形式的”users“：

- -

弹出一个对话框，让用户（译注：原文为”users“）确认他们是否允许网页使用他们的网络摄像头。

- -

当然，最好的方法还是重写句子，去掉其中的代词：

- -

弹出一个对话框，询问用户是否允许网页对网络摄像头的访问。

- -

弹出一个询问用户以获取网络摄像头访问权限的对话框。

- -

最后一种方法（译注：意指去除代词的方法）可能更好一些，因为它不但语法上更加正确，而且还能消除不同语言处理性别问题时所带来的复杂性，因为不同语言对性别的处理可能有不同的规则。因此这种方法无论是对读者（译注：意为阅读英语原文的非英语读者）还是翻译者来说都可以让翻译更简单。

- -

数字和数词

- -

日期

- -

请用”January 1, 1990“这样的形式来表达日期（不包括代码中的日期）。

- -
-
-
    -
  • 正确: February 24, 2006
    • -
  • 错误: February 24th, 2006、24 February, 2006、24/02/2006
    • -
-
-
- -

或者你也可以使用”YYYY/MM/DD“的形式：

- -
-
-
    -
  • 正确: 2006/02/24
    • -
  • 错误: 02/24/2006、24/02/2006、02/24/06
    • -
-
-
- -

年代

- -

请使用”1990s“这种形式来表示年代，但不要使用撇号：

- -
-
-
    -
  • 正确: 1990s
    • -
  • 错误: 1990's
    • -
-
-
- -

数词的复数

- -

数词的复数直接在后面加”s“，同样不要使用撇号：

- -
-
-
    -
  • 正确: 486s
    • -
  • 错误: 486's
    • -
-
-
- -

逗号

- -

应该仅在数字的位数大于等于 5 位时才使用逗号分隔符：

- -
-
-
    -
  • 正确: 4000、54,000
    • -
  • 错误: 4,000、54000
    • -
-
-
- -

标点符号

- -

连续逗号

- -

请使用连续逗号。连续逗号（也叫牛津逗号）是在一个包含三个或以上单词或短语的序列中位于连词前的那个逗号。

- -
-
-
    -
  • 正确: I will travel on trains, planes, and automobiles.
    • -
  • 错误: I will travel on trains, planes and automobiles.
    • -
-
-
- -
-

译注：这种情况在翻译时应将逗号翻译为顿号。”中文翻译规范“一文的”标点符号“一节中也提到了这个问题。

-
- -
-

这一点与 Mozilla 统一规范有冲突，后者要求不要使用连续逗号。MDN 是这一规则的特例。

-
- -

拼写

- -

如果一个单词具有多种拼写，请使用美国英语的拼写。一般来说，Dictionary.com 上的第一个拼写是符合此要求的，除非单词本身即为其他变体形式或主要用于美国以外的国家中。例如，如果你去查”honour“，你会看到一个标注”Chiefly British“，并在其后有一个指向美语标准形式的链接。请不要使用其他的拼写变体。

- -
-
-
    -
  • 正确: localize、honor
    • -
  • 错误: localise、honour
    • -
-
-
- -

术语

- -

HTML 元素

- -

请使用”元素“来表示 HTML 和 XML 元素，不要使用”标记“。另外，请在元素名称两边使用尖括号 ”<>“ 括起来，并使用 {{HTMLElement("code")}} 样式。当文章中第一次出现某个元素的时候，应该用 {{TemplateLink("HTMLElement")}} 宏创建一个指向该元素文档的链接（除非你正在撰写的恰好是该元素的文档页面）。

- -
-
-
    -
  • 正确: {{HTMLElement("span")}} 元素
    • -
  • 错误: span 标记
    • -
-
-
- -

函数参数

- -

在 MDN 上推荐使用 parameters 来表示函数的参数，为了保持一致性，如果可能的话请尽量避免使用”arguments“。

- -

描述用户的操作

- -

在说明一系列操作步骤时，应使用祈使语气来描述用户的操作，并用 UI 组件的名称和其元素类型来标识操作对象。

- -
-
-
    -
  • 正确: 点击编辑按钮
    • -
  • 错误: 点击编辑
    • -
-
-
- -

语态

- -

推荐使用主动语态，但被动语态也可以接受，只是可能会让文章看起来不太正式。建议选择一种并在文章中尽量保持统一。

- -

Wiki 标记及用法

- -

链接

- -

链接是 wiki 中最重要的功能元素之一。这里会介绍一些链接的基本内容，在我们的编辑器指南中的在MDN中创建和编辑链接这篇文章中有关于链接的详细介绍。

- -

我们鼓励适当的添加一些相关文章的链接，这样可以提高页面导航的效率和内容的易发现性。链接不但可以指向其他 MDN 页面（内部链接），也可以指向其他网站的页面（外部链接）。

- -

有两种创建链接的方式：点击编辑器工具栏中的“插入/编辑超链接”按钮（也可以按 Ctrl+K  键（在 Mac 上是 Cmd-K  键）），或者使用 MDN 强大的宏功能来自动创建或根据输入的内容创建链接。

- -

下面列出的指导意见可以帮助你确定创建链接时使用什么样的链接文本：

- - - -

URL 语法

- -

为了保险起见，应始终使用下面的语法来创建链接：

- - - -

其他语法可能无法工作或者不受支持，并有可能会被编辑人员删掉。

- -
-

强调一下，不要使用 about: 和 chrome:// 等语法，因为它们可能无法生效。类似地， javascript: 可能会被最新的浏览器阻止，jar: 同理。

-
- -

页面标签

- -

标签用来提供与页面有关的元数据信息，或者用来标记当前页面在某方面仍需要完善。wiki 中的每个页面都应该包含标签。在如何合理地标记页面这篇指南中有更多关于使用标签的信息。

- -

在编辑文章时，标签位于编辑器的底部，看起来是这样的：

- -

在 MDN 中为页面添加和删除标签

- -

要添加标签，点击标签列表最后的”新建标签……“按钮，然后输入要添加的标签名称。标签会随着你的输入显示自动完成提示。最后按下回车键来确认并提交新标签。可以为一篇文章添加任意多个标签。举个例子，一篇关于在 AJAX 编程中使用 JavaScript 的文章可能需要添加”JavaScript“和”AJAX“这两个标签。

- -

要删除一个标签，点击标签上的”X“图标即可。

- -

标记页面的后续事项

- -

标签还可以用于将文章标记为需要某些后续的工作，用来跟踪文章质量和内容方面的信息。

- -

标记已废弃页面

- -

可使用下面的标签来标记不再使用的页面：

- - - -

SEO 概要

- -

SEO 概要是对一篇文章的简短描述，它会在网页机器爬虫抓取到当前页面时告诉爬虫该文章的概要，当用户搜索到该页面时就会显示此概要信息。另外，在 MDN 内部通过宏来自动生成引导页的时候也会用到它。

- -

默认情况下，文章的第一段内容会被当成是 SEO 概要。但是你可以在编辑器中使用“SEO Summary“样式来手动指定一段内容作为 SEO 概要。

- -

引导页

- -

引导页的层级位于网站层级的顶层，例如 CSS 和 HTML 的主页面就是引导页。引导页具有标准的格式，由以下 3 个部分组成：

- - - -
-

译注：这里的链接原本是指向原文的”Writing a landing page overview“一节，但该节貌似已被删除了，所以链接已失效。这里我找到了一个与其内容相近的小节。

-
- - - -

创建相关页面的链接列表

- -

引导页中的链接列表部分有两列，其 HTML 代码的结构如下：

- -
<div class="row topicpage-table">
-  <div class="section">
-    ... 左侧列 ...
-  </div>
-  <div class="section">
-    ... 右侧列 ...
-  </div>
-</div>
- -

左侧列的顶部是一个 <h2> 标题，用来说明此列的内容是当前主题所包含的文章列表（如”某某的文档和教程“），其下方则是具体的文章列表。该列的标题样式应使用 CSS 类 ”Documentation“，而下方的文章列表是一个 <dl> 列表，其中的每个 <dt> 都包含一个文章的链接和位于 <dd> 中的该目标文章的一两句话的说明。

- -

右侧列则包含一或多个小节，各小节按以下顺序排列：

- -
-
获取社区的帮助
-
该节用来提供当前主题相关的 Matrix 频道和邮件列表信息。标题需使用 CSS 类”Community“。
-
工具
-
可以帮助用户使用当前主题所介绍的技术的工具列表。标题需使用 CSS 类”Tools“。
-
相关主题
-
一些链接到其他相关技术的引导页链接。标题需使用 CSS 类”Related_Topics“。
-
- -

<<<当引导页的标准完成时需要继续完善本节内容>>>

- -

插入图片

- -

在创建或编辑文章时，有时候使用图片会对文章内容有不少好处，特别是文章的技术性很强的时候。可以使用下面的方法来添加一个图片：

- -
    -
  1. 先添加一个图片附件到当前文章中（附件在编辑器的底部）
    2. -
  2. 点击”图像“按钮，弹出对话框
    3. -
  3. 在对话框中的附件下拉列表中，选择刚添加的图片
    4. -
  4. 点击确定按钮
    5. -
- -

其他参考资料

- -

推荐样式指南

- -

如果你在撰写过程中或在格式方面遇到了本文尚未提及的问题，我们建议你参考 Economist 网站的风格指南，如果还是不能解决问题，还可参考芝加哥论文格式。

- -

推荐词典

- -

如果有拼写方面的问题，请参考 Dictionary.com。本网站的拼写检查采用美国英语规则，因此请不要使用其他拼写规则（例如应该使用“color”而不是“colour”）。

- -

我们会继续扩充本指南，因此如果你遇到了本文未提及的问题，请通过 MDC 邮件列表或项目带头人联系我们，让我们了解还需要加入哪些内容。

- -

MDN

- -

MDN 中常用的宏及其说明。

- -

语言、语法和拼写

- -

如果你对提高写作和编辑能力感兴趣，下面的资料会对你有所帮助：

- - diff --git a/files/zh-cn/mdn/guidelines/writing_style_guide/index.html b/files/zh-cn/mdn/guidelines/writing_style_guide/index.html new file mode 100644 index 0000000000..285b2703cb --- /dev/null +++ b/files/zh-cn/mdn/guidelines/writing_style_guide/index.html @@ -0,0 +1,784 @@ +--- +title: MDN Web 文档写作规范 +slug: MDN/Guidelines/Style_guide +tags: + - MDN + - MDN Meta + - MDN Web 文档 + - MDN 规范 + - 写作规范 + - 准则 + - 教程 + - 文档 + - 规范 +translation_of: MDN/Guidelines/Writing_style_guide +--- +
{{MDNSidebar}}
+ +

{{IncludeSubnav("/zh-CN/docs/MDN")}}

+ +

为了提供更加组织化、标准化且易于阅读的文档，MDN Web 文档写作规范明确了文本的组织方式、拼写规则、固定格式等内容，不过这些内容只是指导性的而不是严格的规定，因为比起格式我们对内容更感兴趣，所以没有必要在参与贡献之前强迫自己学习本规范。但是如果有一位勤劳的志愿者在之后编辑了你的文档使它更加符合本规范，也请不要感到惊讶或难过。

+ +

如果你正在寻找一个特定类型的页面应该如何构建的相关细节，请参阅MDN Web 文档页面布局规范。

+ +

本规范主要适用于英文文档。 其他语言可能也有（也欢迎创建）相应的规范。 这些应该作为子页面发布在各个本地化小组的页面中。

+ +
+

译注：本文的写作规范虽说是针对英文所写，但是其中的不少内容也适用于中文，可花点时间阅读一下。另外，中文翻译时的规范请参见《翻译术语表和翻译规范》。

+
+ +

对于那些为MDN以外的站点内容所编写的规范，请参考 Mozilla 统一规范。

+ +

基础部分

+ +

为了使文档保持更好的一致性，所有主流的写作规范指南都是从一些比较基本的写作规范开始的。以下几个小节所概述的这些基本规范内容应该会对你有很大帮助。

+ +

页面标题

+ +

页面标题不仅会在搜索时用到，在页面顶部的面包屑路径中也会被用来表示文档的层级结构。页面标题（就是显示在页面顶部以及搜索结果中标题的部分）可以与页面URL“<locale>/docs/”之后的“铭牌（slug）”部分不同.

+ +

文章标题和段落标题的大写规则

+ +

页面的标题和章节的标头应当使用语句式大写（只大写第一个单词的首字母以及专有名词的首字母），而不应该使用标题式大写：

+ + + +

我们还有很多旧的页面是在这条规范确立之前就已经发布了的。所以只要你愿意，你随时可以更新它们的标题。我们也正在逐步完善它们。

+ +

标题和铭牌的选择

+ +

页面的铭牌应该尽量简短，当创建一个新的层级时，新层级的铭牌最好只由一到两个单词组成。

+ +

而页面的标题长度并没有什么严格的限制，只要合理并且表意明确即可。

+ +

创建新的子目录

+ +

当你要给某个新的主题或主体添加文章时，你通常需要创建一个引导页，然后再把要添加的文章作为子页面添加进去。引导页开篇应当用一两段话来描述一下当前主题或技术，然后添加一个子页面的目录列表，并简要描述每个页面的内容。你可以使用一些我们已经编写好的宏把相关的子页面自动插入到目录列表中。

+ +

例如，JavaScript手册,其结构如下：

+ + + +

尽量避免把文章内容放置在层次结构的顶层，这会降低网站的访问速度，同时搜索和导航的效率也会下降。

+ +

文章内容的通用原则

+ +

在写任何文档时，知道该写多少是很重要的。如果你写的长篇大论，文章读起来就会冗长无味,更不会有人愿意使用它。保持文章内容适量很重要,原因有很多。这其中的原因就有：为了确保读者能够找到他们真正想要的信息，以及为搜索引擎提供足够的优质素材来对文章进行分析和排名。我们将在这里讨论前者（提供读者可能需要的信息）。如果想了解如何让文章更好地被搜索引擎分类和排名，查阅文章How to write for SEO on MDN。

+ +

我们的目标是在页面中包含读者可能需要的所有信息，但又不至于太过冗长。为了实现这个目标,我们给出了一些建议。

+ +

为读者着想

+ +

请记住，这些只是指导性的。其中某些建议并不适用于所有状况。当然你应该始终为你的读者着想。例如，在一篇介绍高级网络技术的文章中，通常不需要像介绍网络编程的文章那样包含过多的网络基本概念。

+ +

提供一个有用的简介

+ +

在开篇或第一个段落标题之前给出文章的简介，以使读者快速了解文章中是否包含他们感兴趣的内容。在指南或教程类的文章中，简介还应该让读者明白文章覆盖了哪些主题，以及文章期望读者能够从中了解到哪些知识。简介中应该包含文章中介绍和讨论的技术、API，并提供相关的链接，同时还应该提供可能会遇到的情况的提示。

+ +
示例：过于简短的简介
+ +

下面这个例子中的简介太过于简短，很多信息都没有包含进来，比如“stroke text”是什么意思，文本会在哪里等。

+ +
+

CanvasRenderingContext2D.strokeText() draws a string.

+
+ +
示例：过于冗长的简介
+ +

下面是上面那个简介的修改版，但是这次它又太过冗长了。其中包含了过多的细节，并且还包含了很多其他方法和属性，但实际上它应该将重点聚焦在 strokeText() 方法上，然后给出详细介绍它的文章的链接即可。

+ +
+

译注：作为例子，内容并不重要，所以就不逐句翻译了。

+
+ +
+

When called, the Canvas 2D API method CanvasRenderingContext2D.strokeText()strokes the characters in the specified string beginning at the coordinates specified, using the current pen color. In the terminology of computer graphics, "stroking" text means to draw the outlines of the glyphs in the string without filling in the contents of each character with color.

+ +

The text is drawn using the context's current font as specified in the context's {{domxref("CanvasRenderingContext2D.font", "font")}} property.

+ +

The placement of the text relative to the specified coordinates are determined by the context's textAlign, textBaseline, and direction properties. textAlign controls the placement of the string relative to the X coordinate specified; if the value is "center", then the string is drawn starting at x - (stringWidth / 2), placing the specified X-coordinate in the middle of the string. If the value is "left", the string is drawn starting at the specified value of x. And if textAlign is "right", the text is drawn such that it ends at the specified X-coordinate.

+ +

(etc etc etc...)

+ +

You can, optionally, provide a fourth parameter that lets you specify a maximum width for the string, in pixels. If you provide this parameter, the text is compressed horizontally or scaled (or otherwise adjusted) to fit inside a space that wide when being drawn.

+ +

You can call the fillText() method to draw a string's characters as filled with color instead of only drawing the outlines of the characters.

+
+ +
示例：这次好多了
+ +

下面这个简介比前两个要好很多。

+ +
+

The {{domxref("CanvasRenderingContext2D")}} method strokeText(), part of the Canvas 2D API, strokes—that is, draws the outlines of—the characters of a specified string, anchored at the position indicated by the given X and Y coordinates. The text is drawn using the context's current {{domxref("CanvasRenderingContext2D.font", "font")}}, and is justified and aligned according to the {{domxref("CanvasRenderingContext2D.textAlign", "textAlign")}}, {{domxref("CanvasRenderingContext2D.textBaseline", "textBaseline")}}, and {{domxref("CanvasRenderingContext2D.direction", "direction")}} properties.

+ +

For more details and further examples, see {{SectionOnPage("/en-US/docs/Learn/JavaScript/Client-side_web_APIs/Drawing_graphics", "Text")}} in the Learning Area as well as our main article on the subject, Drawing text.

+
+ +

多提供一些示例

+ +

文章应该尽量多提供一些示例。实际上，大多数文章都应该包含不止一个例子。使用例子来说明每个参数的用途或每个可能的边界条件是很有必要的。同时还应该用例子来演示常见问题的解决方法，以及应该如何解决使用过程中可能碰到的坑。

+ +

每个例子都应该先给出解释，说明它做了什么，以及读者在阅读或动手尝试之前需要了解的内容。

+ +

另外，每段示例代码都应该就其工作原理给出说明。最好将一段较长的代码分解成多个较小的部分，并提供每个部分的说明，说明时注意细节的层次。如果代码很简单并且不直接涉及到当前 API，可以只给出一个简单的介绍，说明其用途，以及为何要把它放在这里；而如果代码比较复杂、或用到了当前的 API、或在技术上比较有创造性，那么你应该提供更详细的说明。

+ +

如果使用的是在线演示的方式，则可以将 HTML、CSS、JavaScript 拆分到不同的 {{HTMLElement("pre")}} 中，它们在运行时会自动组合到一起，但使用这种方式每个里面都可以有自己的说明。因此这是一种很好很强大的方式。

+ +

过短的文章难以被搜索到

+ +

如果文章过短，那么搜索引擎可能会难以甚至无法对其建立关键字索引。一般来说，文章的主体内容应该至少包含 250-300 个单词。但是也不要对内容确实很少的文章进行刻意的扩充，在可能的情况下尽量遵守该指导原则即可。

+ +

小节、段落和换行

+ +

对于小节的标题，应使用从大到小的方式来定义级别：{{HTMLElement("h2")}}、{{HTMLElement("h3")}}、{{HTMLElement("h4")}} 这样，并且中间不要跳过某一级。因为 H1 已用于文章的标题，因此小节的标题应该从 H2 开始。如果你的文章中小节的层次超过了 3 到 4 级，那么你可能需要考虑将整篇文章拆分成几篇小的文章，然后用一个引导页给出这些文章的链接，并用 {{TemplateLink("Next")}}、{{TemplateLink("Previous")}}、{{TemplateLink("PreviousNext")}} 宏为它们创建导航。

+ +

按下回车键（Enter 或 Return）可以开始一个新的段落。如果只是想换行而不是另起一段，可以按住 Shift 并敲下回车。

+ +

不要创建只包含一个小节的子级别，如果只有一个小节，那么拆分主题就是没有意义的。至少包含两个小节，要么就不要拆分。

+ +

不要让两个小节标题紧挨在一起，这样看起来很丑。每个小节标题的下面至少要放上一段对后面各子小节的简短说明，这会对阅读的人很有帮助。

+ +

列表

+ +

列表的格式应该在所有文章中保持一致，并且应在列表中恰当使用标点和结构合理的句子。不管是哪种类型的列表，都需要对格式进行适当的调整。下面的内容说明了每种列表之间的不同。

+ +

无序列表

+ +

无序列表可以以简洁且有效的方式对内容进行分组显示。每个条目都会以类似“•”的符号来标识。在无序列表中要注意正确使用标点，尤其是每句的最后不要遗漏掉句号。应该以标准写作方式来对待无序列表。

+ +

下面是一个结构良好的无序列表的例子：

+ +
+

在这个例子中需要包括:

+ + +
+ +

可以看到，每个条目的格式都是一致的：首先显示一个“•”符号，然后列出一种情况，然后写上逗号，并在逗号后面添加一些对当前情况的简单说明。

+ +

有序列表

+ +

有序列表用序号来标识每个条目。同样要注意应该在有序列表中使用适当的格式，保持列表的清晰和简洁，这一点与无序列表是类似的。但是有序列表中的某些条目内容可能会很多，因此正确使用标点就更为重要了，因为难免会遇到必须使用复杂句子的情况。

+ +

下面是一个结构良好的有序列表的例子：

+ +
+

为了创建一个好的有序列表，你需要：

+ +
    +
  1. 以一个介绍性的标题开始，以引出后续的序列。我们可以在开始有序列表的序列之前提供这一内容。
    2. +
  2. 开始创建各个序列，这些序列会用数字依次编号。这是有序列表的标准格式，能够很容易地被读者理解。有序列表中的某些条目内容可能会很多，因此正确使用标点是很重要的。
    3. +
  3. 列表序列完成之后，应在后面再提供一段简短的总结。
    4. +
+ +

这段内容就是一个总结。我们已经创建了一个简短的有序列表，解释了创建良好格式的有序列表应遵循的步骤。

+
+ +

有序列表基本都用来表示具有连续性关系的内容，因此应该先深入思考你要用这些内容达到什么目的，然后再去撰写。

+ +

文本格式和样式

+ +

可以使用“样式”下拉列表中的预定义样式来格式化你选定的内容。

+ +
+

“Note”样式用来强调重要提示，就像这个。

+
+ +
+

类似地，“Warning”样式用来创建一个警告框。

+
+ +

除非有特殊需要，否则请不要用 HTML 的 style 属性来手动给内容添加样式。如果你没有找到你需要的预定义样式，可以放置一个 {{IRCLink("mdn")}} 并寻求帮助。

+ +

示例代码的格式和样式

+ +
+

这一小节只是讨论 MDN 文章中的示例代码的样式和格式问题，如果你想了解如何编写示例代码，请参考示例代码指南。

+
+ +

缩进和换行符

+ +

每级缩进都使用两个空格来缩进，并在所有的示例中保持一致。对于代码块的起始语句，应将开大括号“{”与当前语句写在一行上，比如：

+ +
if (condition) {
+  /* handle the condition */
+} else {
+  /* handle the "else" case */
+}
+
+ +

如果一行的代码很长，应在适当的地方换行以避免出现水平滚动条。下面是一个例子：

+ +
if (class.CONDITION || class.OTHER_CONDITION || class.SOME_OTHER_CONDITION
+       || class.YET_ANOTHER_CONDITION ) {
+  /* something */
+}
+
+var toolkitProfileService = Components.classes["@mozilla.org/toolkit/profile-service;1"]
+                           .createInstance(Components.interfaces.nsIToolkitProfileService);
+
+ +

内联代码格式

+ +

对于函数名、变量名、方法名等，应使用“Inline Code”按钮（编辑器中显示为“<>”的按钮）将其设置为内联代码格式（内联代码使用的是 {{HTMLElement("code")}} 元素）。比如：frenchText() 函数。

+ +

方法名后面应该加上小括号：doSomethingUseful()，这样会比较容易将方法与其他代码元素区分开来。

+ +

语法高亮

+ +

Screenshot of the 'Syntax Highlighter' menu.对于整行或多行代码，此时别再使用 {{HTMLElement("code")}}  元素来格式化了，而应该对其进行语法高亮。点击语法高亮器按钮（图标是两个代码块），从语言下拉列表中选择一种合适的语言即可。见右图。

+ +

下面的例子使用了 JavaScript 语法高亮：

+ +
+
for (var i = 0, j = 9; i <= 9; i++, j--)
+  document.writeln("a[" + i + "][" + j + "]= " + a[i][j]);
+
+ +

如果没有在下拉列表中找到你需要的语言，可以选择第一项“没有高亮”，此时代码显示的是不带高亮效果的普通样式：

+ +
x = 42;
+ +

语法定义

+ +

如果你想插入一段语法定义，可以使用样式下拉列表中的“Syntax Box”选项。语法定义的样式与普通代码的样式会有所区别。

+ +

非代码区块

+ +

有些情况下需要用到 <pre> 区块而不是代码区块，此时不会进行语法高亮，也不会显示行号。比如你需要显示树形结构，就可以使用 <pre>：

+ +
root/
+
+    folder1/
+        file1
+
+    folder2/
+        file2
+        file3
+
+ +

插入方法是要先点击”pre“按钮，然后输入想要的内容即可。

+ +

HTML 元素的样式

+ +

HTML 元素的样式有一套自己的规则。遵守这些规则可以让元素及其组件的描述方式保持统一，并且还可以保证能够正确链接到各元素的详细文档页面。

+ +
+
元素名称
+
使用 {{TemplateLink("HTMLElement")}} 宏会生成一个指向该元素详情页的链接。比如，\{{HTMLElement("title")}} 会生成”{{HTMLElement("title")}}“。如果不想生成链接，就将元素名称用尖括号括起来，然后将其设置为内联代码样式，比如 <title>。
+
属性名称
+
请使用粗体。
+
属性定义
+
对正在定义的术语使用 {{TemplateLink("htmlattrdef")}} 宏（如 \{{htmlattrdef("type")}}），这样其他页面就可以使用 {{TemplateLink("htmlattrxref")}} 宏来链接到该页面了（例如 \{{htmlattrxref("attr","属性")}}）。
+
属性值
+
请使用内联代码样式，并且注意字符串两边不要加引号，除非是代码的语法要求加引号。举例：当将 <input> 元素的 type 属性设置为 email 或 tel 时……
+
为属性添加说明标签
+
请不要滥用 {{HTMLVersionInline(5)}} 这样的标签。比如，可以在某个第一次出现的属性名称旁边添加标签，但是不要在每次出现该属性的时候都添加一次。
+
+ +

拉丁文缩写

+ +

在补充说明的括号中

+ +

一般的拉丁文缩写（如：”etc.“、”i.e.“、”e.g.“）都可以用在起补充说明的括号里面。这时应在缩写中添加句号，后面加上逗号或其他恰当的标点。

+ + + +

在一般句子中

+ +

在普通的句子中（即括号的外面），请使用与缩写等价的英文单词或短语。

+ + + +

缩写、拉丁文原文和英文的对照表

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
缩写拉丁文英文
cf.confercompare
e.g.exempli gratiafor example
et al.et aliiand others
etc.et ceteraand so forth, and so on
i.e.id estthat is, in other words
N.B.nota benenote well
P.S.post scriptumpostscript
+ +
+

在使用前请仔细思考使用拉丁文缩写是否真的能带来好处。上面列出的某些缩写很少用到，很多读者可能不知道其意思，还有一些读者可能会分不清其中的某些缩写。另外，如果你决定使用缩写，那么请确保你的用法是正确的。比如，一个很多人经常会犯的错误是将“e.g.”和“i.e.”弄混。

+
+ +

首字母缩写和一般缩写

+ +
+
大写与句号
+
在这两种缩写中（包括国家和组织的缩写，如“US”、“UN”），请使用全大写且不要添加句号。
+
+
    +
  • 正确: XUL
    • +
  • 错误: X.U.L.、Xul
    • +
+
+
缩写展开
+
文章中第一次遇到某个缩写术语时，应该同时给出其展开形式，从而让不了解该缩写的读者能够知道它所指代的内容。如果不确定要不要展开那么就选择展开，或者更好的办法是将其链接到术语表中的对应条目。
+
+
    +
  • 正确: XUL (XML User Interface Language) is Mozilla's XML-based language...
    • +
  • 错误: XUL is Mozilla's XML-based language...
    • +
+
+
缩写的复数形式
+
当需要使用复数形式的缩写时，直接在后面加上“s”即可，请务必不要加撇号。
+
+
    +
  • 正确: CD-ROMs
    • +
  • 错误: CD-ROM's
    • +
+
+
”Versus“、”vs.“和”v.“
+
推荐使用”vs.“。
+
+
    +
  • 正确: this vs. that
    • +
  • 错误: this v. that
    • +
  • 错误: this versus that
    • +
+
+
+ +

大写

+ +

在文章内容中请使用标准英文大写规则，比如对于”World Wide Web“需大写每个单词的首字母。如果”web“和”internet“是单独使用或作为修饰词使用，那么将其全小写也可以——这一指导原则是后来修改过的，所以在 MDN 中你也许会看到很多首字母大写的”Web“和”Internet“。当你编辑文章的时候遇到这种情况，可以随它去，也可以随手修改一下。但是仅仅只是为了修改一下大写的话就没必要专门去编辑一下了。

+ +

对于键盘按键，应该使用普通的大写规则，而不是全大写。比如，是”Enter“而不是”ENTER“。

+ +

简写

+ +

我们倾向于宽松的写作风格，所以你可以按你的喜好来决定是否使用简写（如”don't“、”can't“、”shouldn't“）。

+ +

名称复数

+ +

请使用英文风格的复数形式，不要使用拉丁文或希腊文的形式。

+ +
+
+
    +
  • 正确: syllabuses、octopuses
    • +
  • 错误: syllabi、octopi
    • +
+
+
+ +

连字符

+ +

当两个单词连起来组成另一个单词时，如果前一个单词的最后一个字母是元音字母，并且与后一个单词的第一个字母相同时，应使用连字符。

+ +
+
+
    +
  • 正确: email、re-elect、co-op
    • +
  • 错误: e-mail、reelect、coop
    • +
+
+
+ +

使用性别中立的表述

+ +

在任何性别无关的场合使用性别中立的表述方式是一种比较好的做法，这样可以使你的文章具有普适性。举个例子，如果你正在写的是关于某个男人的行为，那么使用”他“来指代是没问题的；但如果内容并没有特指是男还是女，那么再使用”他“就不太恰当了。

+ +

让我们再看几个例子：

+ +

弹出一个对话框，让用户确认他是否允许网页使用他的网络摄像头。

+ +

弹出一个对话框，让用户确认她是否允许网页使用她的网络摄像头。

+ +

这两句话使用的都是特定性别的表述方式，我们可以将其修改为性别中立的代词：

+ +

弹出一个对话框，让用户确认他们是否允许网页使用他们的网络摄像头。

+ +
+

译注：这里原文为”they“和”their“，在英文中是性别中立的代词。而中文中如果上下文没有强调性别，则”他们“也具有性别中立性。

+
+ +
+

MDN 允许使用这种通用性的语法（尽管在正式用法中这一点还存在争议）来弥补英语在表达中立性别时的不足。将第三人称复数的代词用来表示性别中立代词（即使用”they“、”them“、”their“、”theirs“）是可以接受的，也就是通常所说的”单数形式的‘they’“。

+
+ +

你还可以同时写上两个性别：

+ +

弹出一个对话框，让用户确认他或她是否允许网页使用他/她的网络摄像头。

+ +
+

译注：中文里一般不这么用，所以如果在翻译中遇到这种情况，请简单翻译为”他“即可。”中文翻译规范“一文的”误解：100% 翻译 = 准确“一节中也提到了这个问题。

+
+ +

或者使用复数形式的”users“：

+ +

弹出一个对话框，让用户（译注：原文为”users“）确认他们是否允许网页使用他们的网络摄像头。

+ +

当然，最好的方法还是重写句子，去掉其中的代词：

+ +

弹出一个对话框，询问用户是否允许网页对网络摄像头的访问。

+ +

弹出一个询问用户以获取网络摄像头访问权限的对话框。

+ +

最后一种方法（译注：意指去除代词的方法）可能更好一些，因为它不但语法上更加正确，而且还能消除不同语言处理性别问题时所带来的复杂性，因为不同语言对性别的处理可能有不同的规则。因此这种方法无论是对读者（译注：意为阅读英语原文的非英语读者）还是翻译者来说都可以让翻译更简单。

+ +

数字和数词

+ +

日期

+ +

请用”January 1, 1990“这样的形式来表达日期（不包括代码中的日期）。

+ +
+
+
    +
  • 正确: February 24, 2006
    • +
  • 错误: February 24th, 2006、24 February, 2006、24/02/2006
    • +
+
+
+ +

或者你也可以使用”YYYY/MM/DD“的形式：

+ +
+
+
    +
  • 正确: 2006/02/24
    • +
  • 错误: 02/24/2006、24/02/2006、02/24/06
    • +
+
+
+ +

年代

+ +

请使用”1990s“这种形式来表示年代，但不要使用撇号：

+ +
+
+
    +
  • 正确: 1990s
    • +
  • 错误: 1990's
    • +
+
+
+ +

数词的复数

+ +

数词的复数直接在后面加”s“，同样不要使用撇号：

+ +
+
+
    +
  • 正确: 486s
    • +
  • 错误: 486's
    • +
+
+
+ +

逗号

+ +

应该仅在数字的位数大于等于 5 位时才使用逗号分隔符：

+ +
+
+
    +
  • 正确: 4000、54,000
    • +
  • 错误: 4,000、54000
    • +
+
+
+ +

标点符号

+ +

连续逗号

+ +

请使用连续逗号。连续逗号（也叫牛津逗号）是在一个包含三个或以上单词或短语的序列中位于连词前的那个逗号。

+ +
+
+
    +
  • 正确: I will travel on trains, planes, and automobiles.
    • +
  • 错误: I will travel on trains, planes and automobiles.
    • +
+
+
+ +
+

译注：这种情况在翻译时应将逗号翻译为顿号。”中文翻译规范“一文的”标点符号“一节中也提到了这个问题。

+
+ +
+

这一点与 Mozilla 统一规范有冲突，后者要求不要使用连续逗号。MDN 是这一规则的特例。

+
+ +

拼写

+ +

如果一个单词具有多种拼写，请使用美国英语的拼写。一般来说，Dictionary.com 上的第一个拼写是符合此要求的，除非单词本身即为其他变体形式或主要用于美国以外的国家中。例如，如果你去查”honour“，你会看到一个标注”Chiefly British“，并在其后有一个指向美语标准形式的链接。请不要使用其他的拼写变体。

+ +
+
+
    +
  • 正确: localize、honor
    • +
  • 错误: localise、honour
    • +
+
+
+ +

术语

+ +

HTML 元素

+ +

请使用”元素“来表示 HTML 和 XML 元素，不要使用”标记“。另外，请在元素名称两边使用尖括号 ”<>“ 括起来，并使用 {{HTMLElement("code")}} 样式。当文章中第一次出现某个元素的时候，应该用 {{TemplateLink("HTMLElement")}} 宏创建一个指向该元素文档的链接（除非你正在撰写的恰好是该元素的文档页面）。

+ +
+
+
    +
  • 正确: {{HTMLElement("span")}} 元素
    • +
  • 错误: span 标记
    • +
+
+
+ +

函数参数

+ +

在 MDN 上推荐使用 parameters 来表示函数的参数，为了保持一致性，如果可能的话请尽量避免使用”arguments“。

+ +

描述用户的操作

+ +

在说明一系列操作步骤时，应使用祈使语气来描述用户的操作，并用 UI 组件的名称和其元素类型来标识操作对象。

+ +
+
+
    +
  • 正确: 点击编辑按钮
    • +
  • 错误: 点击编辑
    • +
+
+
+ +

语态

+ +

推荐使用主动语态，但被动语态也可以接受，只是可能会让文章看起来不太正式。建议选择一种并在文章中尽量保持统一。

+ +

Wiki 标记及用法

+ +

链接

+ +

链接是 wiki 中最重要的功能元素之一。这里会介绍一些链接的基本内容，在我们的编辑器指南中的在MDN中创建和编辑链接这篇文章中有关于链接的详细介绍。

+ +

我们鼓励适当的添加一些相关文章的链接，这样可以提高页面导航的效率和内容的易发现性。链接不但可以指向其他 MDN 页面（内部链接），也可以指向其他网站的页面（外部链接）。

+ +

有两种创建链接的方式：点击编辑器工具栏中的“插入/编辑超链接”按钮（也可以按 Ctrl+K  键（在 Mac 上是 Cmd-K  键）），或者使用 MDN 强大的宏功能来自动创建或根据输入的内容创建链接。

+ +

下面列出的指导意见可以帮助你确定创建链接时使用什么样的链接文本：

+ + + +

URL 语法

+ +

为了保险起见，应始终使用下面的语法来创建链接：

+ + + +

其他语法可能无法工作或者不受支持，并有可能会被编辑人员删掉。

+ +
+

强调一下，不要使用 about: 和 chrome:// 等语法，因为它们可能无法生效。类似地， javascript: 可能会被最新的浏览器阻止，jar: 同理。

+
+ +

页面标签

+ +

标签用来提供与页面有关的元数据信息，或者用来标记当前页面在某方面仍需要完善。wiki 中的每个页面都应该包含标签。在如何合理地标记页面这篇指南中有更多关于使用标签的信息。

+ +

在编辑文章时，标签位于编辑器的底部，看起来是这样的：

+ +

在 MDN 中为页面添加和删除标签

+ +

要添加标签，点击标签列表最后的”新建标签……“按钮，然后输入要添加的标签名称。标签会随着你的输入显示自动完成提示。最后按下回车键来确认并提交新标签。可以为一篇文章添加任意多个标签。举个例子，一篇关于在 AJAX 编程中使用 JavaScript 的文章可能需要添加”JavaScript“和”AJAX“这两个标签。

+ +

要删除一个标签，点击标签上的”X“图标即可。

+ +

标记页面的后续事项

+ +

标签还可以用于将文章标记为需要某些后续的工作，用来跟踪文章质量和内容方面的信息。

+ +

标记已废弃页面

+ +

可使用下面的标签来标记不再使用的页面：

+ + + +

SEO 概要

+ +

SEO 概要是对一篇文章的简短描述，它会在网页机器爬虫抓取到当前页面时告诉爬虫该文章的概要，当用户搜索到该页面时就会显示此概要信息。另外，在 MDN 内部通过宏来自动生成引导页的时候也会用到它。

+ +

默认情况下，文章的第一段内容会被当成是 SEO 概要。但是你可以在编辑器中使用“SEO Summary“样式来手动指定一段内容作为 SEO 概要。

+ +

引导页

+ +

引导页的层级位于网站层级的顶层，例如 CSS 和 HTML 的主页面就是引导页。引导页具有标准的格式，由以下 3 个部分组成：

+ + + +
+

译注：这里的链接原本是指向原文的”Writing a landing page overview“一节，但该节貌似已被删除了，所以链接已失效。这里我找到了一个与其内容相近的小节。

+
+ + + +

创建相关页面的链接列表

+ +

引导页中的链接列表部分有两列，其 HTML 代码的结构如下：

+ +
<div class="row topicpage-table">
+  <div class="section">
+    ... 左侧列 ...
+  </div>
+  <div class="section">
+    ... 右侧列 ...
+  </div>
+</div>
+ +

左侧列的顶部是一个 <h2> 标题，用来说明此列的内容是当前主题所包含的文章列表（如”某某的文档和教程“），其下方则是具体的文章列表。该列的标题样式应使用 CSS 类 ”Documentation“，而下方的文章列表是一个 <dl> 列表，其中的每个 <dt> 都包含一个文章的链接和位于 <dd> 中的该目标文章的一两句话的说明。

+ +

右侧列则包含一或多个小节，各小节按以下顺序排列：

+ +
+
获取社区的帮助
+
该节用来提供当前主题相关的 Matrix 频道和邮件列表信息。标题需使用 CSS 类”Community“。
+
工具
+
可以帮助用户使用当前主题所介绍的技术的工具列表。标题需使用 CSS 类”Tools“。
+
相关主题
+
一些链接到其他相关技术的引导页链接。标题需使用 CSS 类”Related_Topics“。
+
+ +

<<<当引导页的标准完成时需要继续完善本节内容>>>

+ +

插入图片

+ +

在创建或编辑文章时，有时候使用图片会对文章内容有不少好处，特别是文章的技术性很强的时候。可以使用下面的方法来添加一个图片：

+ +
    +
  1. 先添加一个图片附件到当前文章中（附件在编辑器的底部）
    2. +
  2. 点击”图像“按钮，弹出对话框
    3. +
  3. 在对话框中的附件下拉列表中，选择刚添加的图片
    4. +
  4. 点击确定按钮
    5. +
+ +

其他参考资料

+ +

推荐样式指南

+ +

如果你在撰写过程中或在格式方面遇到了本文尚未提及的问题，我们建议你参考 Economist 网站的风格指南，如果还是不能解决问题，还可参考芝加哥论文格式。

+ +

推荐词典

+ +

如果有拼写方面的问题，请参考 Dictionary.com。本网站的拼写检查采用美国英语规则，因此请不要使用其他拼写规则（例如应该使用“color”而不是“colour”）。

+ +

我们会继续扩充本指南，因此如果你遇到了本文未提及的问题，请通过 MDC 邮件列表或项目带头人联系我们，让我们了解还需要加入哪些内容。

+ +

MDN

+ +

MDN 中常用的宏及其说明。

+ +

语言、语法和拼写

+ +

如果你对提高写作和编辑能力感兴趣，下面的资料会对你有所帮助：

+ + diff --git a/files/zh-cn/mdn/kuma/index.html b/files/zh-cn/mdn/kuma/index.html deleted file mode 100644 index d506a15fbe..0000000000 --- a/files/zh-cn/mdn/kuma/index.html +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: 'Kuma: MDN 的 wiki 平台' -slug: MDN/Kuma -tags: - - Kuma - - wiki - - 平台 -translation_of: MDN/Kuma ---- -
{{MDNSidebar}}{{IncludeSubnav("/en-US/docs/MDN")}}
- -

Kuma 是驱动 MDN Web Docs 的 Django 程序。

- -

{{SubpagesWithSummaries}}

- -

了解Kuma

- -

想要了解Kuma，你可以：

- - diff --git a/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html b/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html deleted file mode 100644 index d0ca0069fb..0000000000 --- a/files/zh-cn/mdn/structures/live_samples/simple_live_sample_demo/index.html +++ /dev/null @@ -1,31 +0,0 @@ ---- -title: A simple demo of a live code sample -slug: MDN/Structures/Live_samples/Simple_live_sample_demo -translation_of: MDN/Structures/Live_samples/Simple_live_sample_demo ---- -
{{MDNSidebar}}

The_example

- -

This is a very simple example showing you how to do a live demo in MDN. For more information, see Live samples.

- -
<form>
-  <label>Try me<input type="text" name="name"></label>
-  <input type="submit" value="go">
-</form>
- -
form {
-  border-radius: 10px;
-  background: powderblue;
-}
- -
var f = document.querySelector('form');
-
-f.addEventListener('submit', function(ev) {
-  ev.preventDefault();
-  document.querySelectorAll('input')[1].value = 'sending';
-}, false);
- -

{{ EmbedLiveSample('The_example', '', '', '') }}

- -

 

- -

 

diff --git a/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html b/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html new file mode 100644 index 0000000000..3809bb2094 --- /dev/null +++ b/files/zh-cn/mdn/structures/macros/commonly-used_macros/index.html @@ -0,0 +1,222 @@ +--- +title: 常用的宏 +slug: MDN/Structures/Macros/Custom_macros +tags: + - CSS + - 参考 + - 宏 + - 结构 +translation_of: MDN/Structures/Macros/Commonly-used_macros +--- +
{{MDNSidebar}}
+ +

本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见使用宏和使用链接宏。对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见其它宏。这里也有一份 MDN 上所有宏的完整列表。

+ +

对于适合你使用的样式，另见 CSS 样式指南。

+ +

链接

+ +

创建一个单独的超链接

+ +

通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的链接按钮创建链接。

+ + + +

链接到参考文档页面

+ +

有各种宏用来链接到 MDN 上特定参考区域里的页面。

+ + + +

链接到漏洞和互联网中继聊天（IRC）

+ + + +

用于多页面指南的导航帮助

+ +

{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。

+ +

代码示例

+ +

实样

+ + + +

附上的示例文件

+ + + +

侧边栏组

+ +

There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。

+ + + +

（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）

+ +

通用格式化

+ +

API 文档的行内指示器

+ +

{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常当描述一个对象的属性或一个函数的参数的列表。

+ +

用法: \{{optional_inline()}} 或 \{{ReadOnlyInline()}} 。示例：

+ +
+
isCustomObject {{ReadOnlyInline()}}
+
如果为真，指示该对象是一个自定义对象。
+
parameterX {{ optional_inline() }}
+
Blah blah blah...
+
+ +

状态和兼容性指示器

+ +

没有附加参数的行内指示器

+ +

非标准的

+ +

{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。

+ +
语法
+ +

\{{non-standard_inline}}

+ +
示例
+ + + +

实验性的

+ +

{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。

+ +
语法
+ +

\{{experimental_inline}}

+ +
示例
+ + + +

提供明确技术的指示器

+ +

在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。

+ +

不赞成的

+ +

{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。注意：“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。

+ +

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

+ +
语法
+ +

\{{deprecated_inline}} 或 \{{deprecated_inline("gecko5")}}

+ +
示例
+ + + +

已废弃的

+ +

{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。

+ +

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

+ +
语法
+ +

\{{obsolete_inline}} 或 \{{obsolete_inline("js1.8.5")}}

+ +
示例
+ + + +

模板徽标

+ +

这些宏大多数被用于 WebAPI 页面。见 {{anch("Creating new badges")}} 关于创建一个新徽标的信息。

+ +

页面或区域标头指示

+ +

这些模板与上述内联模板具有相同的语义。 模板应直接放置在参考页面的主页标题（或面包屑导航，如果可用）的下面。 它们也可以用于标记页面上的某个部分。

+ + + +

指示一个功能在Web workers中可用

+ +

 {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在Web worker 上下文中可用。

+ +

版本信息宏

+ +

这些宏被用来指示这个语段只与一个产品的特定版本有关。

+ + + +
    +
+ +
    +
diff --git a/files/zh-cn/mdn/structures/macros/custom_macros/index.html b/files/zh-cn/mdn/structures/macros/custom_macros/index.html deleted file mode 100644 index 3809bb2094..0000000000 --- a/files/zh-cn/mdn/structures/macros/custom_macros/index.html +++ /dev/null @@ -1,222 +0,0 @@ ---- -title: 常用的宏 -slug: MDN/Structures/Macros/Custom_macros -tags: - - CSS - - 参考 - - 宏 - - 结构 -translation_of: MDN/Structures/Macros/Commonly-used_macros ---- -
{{MDNSidebar}}
- -

本页列举了许多被创建用于 MDN 的通用宏。对于使用这些宏的基础信息，见使用宏和使用链接宏。对于不常用的，只在特定上下文或不赞成使用的宏的信息，参见其它宏。这里也有一份 MDN 上所有宏的完整列表。

- -

对于适合你使用的样式，另见 CSS 样式指南。

- -

链接

- -

创建一个单独的超链接

- -

通常来说，你不需要使用宏来创建任意的链接。使用编辑器界面上的链接按钮创建链接。

- - - -

链接到参考文档页面

- -

有各种宏用来链接到 MDN 上特定参考区域里的页面。

- - - -

链接到漏洞和互联网中继聊天（IRC）

- - - -

用于多页面指南的导航帮助

- -

{{TemplateLink("Previous")}}，{{TemplateLink("Next")}}，和 {{TemplateLink("PreviousNext")}} 提供导航控制用于序列中的部分文章。对于单向模板，唯一需要的参数是序列中前一篇或后一篇文章的维基（wiki）地址。对于 {{TemplateLink("PreviousNext")}}，需要两个适当的文章地址作为参数。第一个参数用于前一篇文章，而第二个用于后一篇文章。

- -

代码示例

- -

实样

- - - -

附上的示例文件

- - - -

侧边栏组

- -

There templates for almost every large collection of pages. 它们通常链接回参考/指南/教程的主页面（这经常被需要，因为我们的面包屑有时做不到这样）并把文章放入适当的类别中。

- - - -

（译者注：通过在 background-color 页面测试，编辑页面中 "Summary" 上一行的 {{CSSRef}} 用于生成页面左侧的 CSS 参考链接的侧边栏）

- -

通用格式化

- -

API 文档的行内指示器

- -

{{TemplateLink("optional_inline")}} 和 {{TemplateLink("ReadOnlyInline")}} 被用于 API 文档，通常当描述一个对象的属性或一个函数的参数的列表。

- -

用法: \{{optional_inline()}} 或 \{{ReadOnlyInline()}} 。示例：

- -
-
isCustomObject {{ReadOnlyInline()}}
-
如果为真，指示该对象是一个自定义对象。
-
parameterX {{ optional_inline() }}
-
Blah blah blah...
-
- -

状态和兼容性指示器

- -

没有附加参数的行内指示器

- -

非标准的

- -

{{TemplateLink("non-standard_inline")}} 插入一个行内标记指示当前 API 还没有被标准化，并且不在一个标准行径上。

- -
语法
- -

\{{non-standard_inline}}

- -
示例
- - - -

实验性的

- -

{{TemplateLink("experimental_inline")}} 插入一个行内标记指示当前 API 没有被广泛地实现，并且在以后可能会改变。

- -
语法
- -

\{{experimental_inline}}

- -
示例
- - - -

提供明确技术的指示器

- -

在这些宏当中，其参数（在明确规定下）应该是 "html", "js", "css" 或 "gecko" 当中的一个字符串，其后跟着版本号。

- -

不赞成的

- -

{{TemplateLink("deprecated_inline")}} 插入一个不赞成的行内标记来劝阻一个官方不赞成的 API 的使用。注意：“不赞成的”表示该项不该再被使用，但是仍然可用。如果你想表示它不再起作用了，使用术语“已废弃”。

- -

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

- -
语法
- -

\{{deprecated_inline}} 或 \{{deprecated_inline("gecko5")}}

- -
示例
- - - -

已废弃的

- -

{{TemplateLink("obsolete_inline")}} 插入一个已废弃的行内标记来阻止使用，比如正式废弃的一个函数，方法或属性。

- -

不要在任何浏览器不可知的区域（ HTML, APIs, JS, CSS, … ）内使用参数。

- -
语法
- -

\{{obsolete_inline}} 或 \{{obsolete_inline("js1.8.5")}}

- -
示例
- - - -

模板徽标

- -

这些宏大多数被用于 WebAPI 页面。见 {{anch("Creating new badges")}} 关于创建一个新徽标的信息。

- -

页面或区域标头指示

- -

这些模板与上述内联模板具有相同的语义。 模板应直接放置在参考页面的主页标题（或面包屑导航，如果可用）的下面。 它们也可以用于标记页面上的某个部分。

- - - -

指示一个功能在Web workers中可用

- -

 {{TemplateLink("AvailableInWorkers")}} 宏插入一个本地化的指示框，指示一个功能在Web worker 上下文中可用。

- -

版本信息宏

- -

这些宏被用来指示这个语段只与一个产品的特定版本有关。

- - - -
    -
- -
    -
diff --git a/files/zh-cn/mdn/yari/index.html b/files/zh-cn/mdn/yari/index.html new file mode 100644 index 0000000000..d506a15fbe --- /dev/null +++ b/files/zh-cn/mdn/yari/index.html @@ -0,0 +1,24 @@ +--- +title: 'Kuma: MDN 的 wiki 平台' +slug: MDN/Kuma +tags: + - Kuma + - wiki + - 平台 +translation_of: MDN/Kuma +--- +
{{MDNSidebar}}{{IncludeSubnav("/en-US/docs/MDN")}}
+ +

Kuma 是驱动 MDN Web Docs 的 Django 程序。

+ +

{{SubpagesWithSummaries}}

+ +

了解Kuma

+ +

想要了解Kuma，你可以：

+ + -- cgit v1.2.3-54-g00ecf