CoffeeScript Cookbook 作者指南：如何编写高质量技术教程

前言

CoffeeScript Cookbook 是一个专注于提供高质量 CoffeeScript 编程示例的技术资源库。作为技术作者，编写清晰、实用的教程需要遵循一定的规范和技巧。本文将详细介绍如何为该项目贡献优质内容。

基础写作规范

1. 标准格式模板

每个技术教程应采用"问题-解决方案-讨论"的三段式结构：

---
layout: recipe
title: 教程标题
chapter: 所属章节
---

## 问题

简明描述读者可能遇到的具体问题，使用第二人称视角：
"你需要从字符串中提取特定部分"
"你需要将浮点数格式化为带美元符号、千位分隔符和两位小数的货币格式"

## 解决方案

用一句话概括解决方案，并提供示例代码：

```coffeescript
# 使用数组范围下标或JavaScript的slice函数
str = "CoffeeScript"
part = str[0..4]  # => "Coffee"

讨论

详细解释解决方案的工作原理、注意事项和边界情况：

"这种方法利用了CoffeeScript的数组切片语法，实际上是调用了JavaScript的substring方法。需要注意的是，当索引超出范围时..."

### 2. 代码展示最佳实践

在展示代码时，应遵循以下规范：

1. 使用正确的语法高亮标记：
```markdown
{% highlight coffeescript %}
square = (x) -> x * x
{% endhighlight %}

2. 显示关键代码的输出结果：

[1,2,3].map (x) -> x * 2
# => [2, 4, 6]

3. 避免无意义的输出展示，如console.log等副作用操作

内容质量把控

1. 选题标准

优秀的教程应满足以下条件：

• 解决真实存在的开发问题
• 提供最佳实践而非炫技代码
• 保持CoffeeScript的惯用风格
• 有明确的适用场景

不适合收录的内容包括：

• 仅展示语言特性的炫技代码
• 过于特定领域的解决方案
• 存在严重性能或安全问题的实现

2. 技术深度控制

对于复杂主题，应分层讲解：

1. 基础用法示例
2. 常见应用场景
3. 高级技巧和注意事项
4. 性能考量（如适用）

章节组织规范

1. 创建新教程

1. 在对应章节目录下创建markdown文件
2. 文件名应反映问题描述，如"字符串反转.md"
3. 确保YAML元数据正确：

layout: recipe
title: 教程标题
chapter: 所属章节

2. 创建新章节

1. 在章节索引中添加新章节名称
2. 创建对应的目录（使用下划线代替空格）
3. 添加index.html文件并设置正确的layout

常见问题解答

Q: 能否修改现有教程？

A: 鼓励改进现有内容，但需确保修改确实提升了质量。

Q: 纯JavaScript方案可以收录吗？

A: 可以，只要该方案在CoffeeScript环境下有效且实用。

Q: 效率高但可读性差的方案如何处理？

A: 可以作为备选方案提供，但需明确说明权衡点。

版权注意事项

1. 仅提交拥有合法使用权限的代码
2. 禁止直接复制其他网站的示例而不加解释
3. 所有内容默认采用CC BY 3.0许可协议

结语

编写优秀的技术教程需要平衡简洁性和完整性。记住，你的内容可能会被开发者反复查阅，因此清晰的结构和准确的信息至关重要。通过遵循这些指南，你将能够为CoffeeScript社区贡献高质量的学习资源。