贡献指南
相关源文件
本文档概述了您如何为 "30 seconds of code" 项目做出贡献，该项目是一个由社区支持的各种编程语言的短代码片段集合。这些指南旨在确保所有贡献的一致性和质量。
有关编码标准和最佳实践的详细信息，请参阅编码标准。
如何提供帮助
"30 seconds of code" 是一个社区驱动的项目，社区的贡献对其持续增长和改进至关重要。以下是您可以提供帮助的方式：
- 提交错误、改进或错别字的问题
- 创建包含修复或新内容的拉取请求
- 帮助改进文档
来源: CONTRIBUTING.md5-8
贡献工作流程
下图说明了项目贡献的一般工作流程：
来源: CONTRIBUTING.md14-15
基本规则
在为项目贡献时，请遵守以下基本规则：
- 始终对他人保持礼貌和尊重，并听从维护者的建议。
- 在更改网站内容时，仅修改
content/snippets 或 content/collections 目录下的文件。
违反任何这些规则将导致您的拉取请求被关闭。
来源: CONTRIBUTING.md10-15
内容组织
下图说明了内容在仓库中的组织方式：
来源: CONTRIBUTING.md14-15
写作指南
网站上的所有内容都应遵循这些准则，以保持一致性和质量。这些准则涵盖了写作的多个方面，从语言到格式。
语言准则
- 使用受众理解的词语和语言
- 所有内容均使用美式拼写
- 写短句子（理想情况下20个单词或更少）
- 确保每个句子只有一个重点
- 删除不必要或重复的词语
- 避免使用含义间接或反讽的习语和短语
- 避免使用行话和过于技术性的术语
- 力求达到或低于十年级阅读水平
- 自然地使用缩略语，但不要过度使用
- 避免使用指示性语言（例如，“上方”、“下方”），除非指代同一内容中的章节
来源: CONTRIBUTING.md20-34
语气和语调
| 语态类型 | 何时使用 | 示例 |
|---|
| 主动语态 | 大多数情况 | "使用此方法转换数据" |
| 被动语态 | 当强调动作而非主体时 | "数据由该方法转换" |
| 祈使语态 | 在编写代码片段文档时 | "使用此方法" |
| 允许性语言 | 避免 | ❌ "你可以使用此方法" |
来源:
文本格式指南
下图说明了关键的格式指南：
来源: CONTRIBUTING.md43-132
大写
- 大写句子开头的字母，其余字母小写
- 保留术语（例如“JavaScript”）、缩略语（例如“CRUD”）、产品（例如“GitHub Actions”）或商标（例如“Netlify”）的原始大小写
来源: CONTRIBUTING.md43-47
标点符号
- 在常规文本中避免使用“&”（和号）；改用“and”拼写
- 撇号用于省略的数字或字母、缩写或所有格
- 使用引号来定义单词或引用文本
- 避免在句子中间使用句号（内联代码块或“Node.js”等术语除外）
- 冒号应谨慎使用，主要用于引出列表
- 句号仅用于结束完整句子
- 问号应谨慎使用
- 不要使用牛津逗号
- 不要使用逗号分隔项目符号或编号列表项
- 尽量避免使用感叹号
来源:
术语
- 谨慎使用术语，仅在必要时使用
- 只使用行业标准或已确立的术语
- 如果不确定读者是否理解，请解释术语
- 尽可能链接到网站上的相关内容
来源:
强调
- 谨慎使用粗体来突出重要信息
- 不要使用粗体创建标题
- 使用斜体引用文本（短的逐字短语）
- 使用引用块表示需要注意的较长句子（每页限一个）
来源:
日期
- 日期使用美式英语格式（月 日, 年）
- 月份使用3个字母的缩写，后跟句号
- 日期数字不要添加序数后缀
- 不要以数字形式书写日期
来源:
代码
- 将内联代码块包装在适当的视觉元素中
- 将重要值（数字、字符串、布尔值）包装在适当的视觉元素中
- 使用多行代码块来处理跨越多行的代码
- 为多行代码块提供适当的语言上下文和高亮
- 在描述原生代码时，使用完整名称或最接近官方文档的名称（例如，“Function.prototype.apply()”）
- 不要在标题中使用代码块
来源:
人称代词
| 代词 | 何时使用 |
|---|
| “我”或“我的” | 用于个人观点、经验或个人语气 |
| “我们”或“我们的” | 指代“30 seconds of code”团队时 |
| “我们”或“我们的” | 当听众在跟进时，您希望听起来令人放心时 |
| “你”或“你的” | 当向听众解释某事时，您希望听起来有权威性时 |
来源:
标题
- 如果标题格式为句子，则首字母大写，其余小写
- 如果标题不以句子形式格式化，则每个单词的首字母可以大写
- 标题中避免使用标点符号（问答型文章的问号除外）
- 保持标题简短（一行以内）
- 标题限制为一句话
- 使用能帮助用户理解相关内容的主题的标题
- 使用标题使内容更易于浏览
来源:
列表
- 尽可能使用项目符号（无序）列表
- 文章列表或步骤序列使用编号（有序）列表
- 对于代码片段的文档，优先使用项目符号列表而非编号列表
- 列表项应以大写字母开头
- 列表项末尾不要使用逗号或分号
- 如果任何列表项包含两句或更多句子，则所有列表项都要使用标点符号
- 如果所有列表项都是一个句子或片段，则不使用标点符号
来源:
操作和链接
- 操作应尽可能以强动词开头（例如，“搜索”，“查看全部”）
- 操作的第一个单词大写，其余小写
- 以可预测的方式标记链接
- 如果链接指向具有自己标题的页面，则优先使用内容的原始标题
- 完整句子中的链接应仅应用于相关文本，而非整个句子
- 完整句子中的链接必须具有描述性，无论是其本身还是基于其周围上下文
来源:
替代文本
- 尽可能为视觉内容提供替代文本
- 装饰性视觉内容使用空替代文本
- 替代文本应帮助用户浏览网站并提供无障碍体验
- 使用简洁的语言，避免不必要的词语
来源:
内容验证过程
当您向 "30 seconds of code" 项目提交内容时，它会经过一个审查过程，以确保其符合质量标准。下图说明了此过程：
来源:
示例：良好与不良内容格式
以下是根据准则展示的良好与不良内容格式的对比表格：
| 指南 | 良好示例 | 不良示例 |
|---|
| 句子长度 | "此函数将数组转换为对象。它使用键值对。" | "此函数通过获取键值对并将其映射来创建新的对象结构以进行数据操作，从而将数组转换为对象。" |
| 语态 | "使用此方法转换数据。" | "如果您想的话，可以使用此方法转换数据。" |
| 大写 | "Function.prototype.apply() 方法" | "function.prototype.Apply() 方法" |
| 代码格式化 | "使用 Array.prototype.map() 转换元素。" | "使用 Array.prototype.map() 转换元素。" |
| 标题 | "将数组转换为对象" | "如何在JavaScript中将数组转换为对象 - 综合指南" |
| 列表 | • 第一个项目
• 第二个项目 | • 第一个项目，
• 第二个项目， |
来源:
遵循这些准则，您将有助于维护 "30 seconds of code" 项目的质量和一致性，使其成为全球开发人员的宝贵资源。