Rails 文档项目

随着 Rails Wiki 项目的近期复兴，我们看到人们询问 Rails 的各种文档是如何整合在一起的。我认为，最好能阐述一下 Rails Activists 在未来将如何看待所有这些文档的整合。

Rails 是一个庞大且成熟的框架，拥有大量功能——随着 Merb 的合并，未来将有更多内容需要学习。因此，它对所有级别的开发人员都提出了挑战，他们试图理解如何有效地使用 Rails。有很多资源可以帮助学习过程，包括商业书籍和杂志、屏幕录像和播客、教程、博客文章以及培训课程。但还有一系列官方书面文档项目。

没有一种放之四海而皆准的文档。不同的开发人员在学习 Rails 时带来了不同的技能、背景和专业成熟度。官方文档至少有四个级别，它们相互重叠但服务于不同的需求。

• 内联文档，代码本身的注释（您可以通过在任何 Rails 项目中运行 rake doc:rails 来查看）。
• Rails 指南
• Rails 书籍（Rails 3.0 的一个新项目）
• Rails Wiki

尽管乍一看似乎有很大的重叠，但我们的感觉是，这些项目中的每一个都占据着一个独特（且有价值）的利基市场。

RDoc

• 提供即时语法问题帮助
• 由核心开发人员维护，通常是最新的

Rails 指南

• 为特定问题领域提供集中的“操作方法”帮助
• 面向中级开发人员，可能已有 Rails 经验
• 拥有大量现有的高质量材料
• 已在持续修订，以跟踪边缘 Rails 的变化
• 可以包含特定版本的教程代码示例
• 可以作为核心 Rails 的一部分交付，为新开发人员提供“触手可及的指导”

Rails 书籍

• 提供高级架构指导和整体视图，说明各部分如何协同工作
• 深入探讨“Rails 方式”的理念，以便读者能够理解为什么框架会这样工作
• 面向刚接触 Rails 的开发人员或希望从“树木”转向“森林”视野的开发人员
• 在 Rails 3 时期，提供帮助以概念化 Rails 和在替代模块（ORM、路由 DSL 等）之间进行选择
• 可以借鉴 Merb 的经验，同时进行翻译并引入多位作者的贡献
• 很大程度上独立于版本
• 以一种独立的指南不具备的方式，提供结构化的端到端文档路径

Rails Wiki

• 社区驱动的文档，可以快速响应新软件和新问题
• 外部信息链接的良好存储库
• 可能成为 Rails 本身在底层软件中的展示窗口
• 一个可以存放社区累积知识的地方，即使是那些不常需要的部分

值得注意的是，我们并不认为这四个项目是完全独立且没有相互作用的。特别是，书籍很可能会为寻求更多细节的读者链接到指南，而指南则会为寻求更多高级指导的读者链接到书籍。我们还预计 Wiki 会将读者引向指南和书籍（以及其他信息来源）。

那么，您能做些什么来参与其中呢？如果您是作家、翻译或编辑，这些文档项目中的任何一个都会很乐意得到您的帮助。

• 要为 RDoc 做出贡献，请编写带有良好注释的 Rails patch，或查看 docrails 项目。
• 要帮助 Rails 指南，请联系 Pratik Naik 或 Mike Gunderloy，或在 freenode 的 #docrails IRC 频道上露面。
• 要参与 Rails 书籍项目，请联系 Matt Aimonetti。
• 要为 Rails Wiki 添加内容，请加入 rubyonrails-wiki 群组。