More at rubyonrails.org: Overview | Download | Deploy | Code | Screencasts | Documentation | Ecosystem | Community | Blog

Contribute to the Rails Guides

Rails Guides aim to improve the Rails documentation and to make the barrier to entry as low as possible. A reasonably experienced developer should be able to use the guides to come up to speed on Rails quickly. Our sponsors have contributed prizes for those who write an entire guide, but there are many other ways to contribute.

1 How to Contribute?

  • We have an open commit policy: anyone is welcome to contribute and to review contributions.
  • docrails is hosted on GitHub and has public write access.
  • Guides are written in Textile, and reside at railties/guides/source in the docrails project.
  • Follow the Rails Guides Conventions.
  • Assets are stored in the railties/guides/assets directory.
  • Sample format : Active Record Associations.
  • Sample output : Active Record Associations.
  • You can build the Guides during testing by running bundle exec rake generate_guides in the railties directory.
  • You’re encouraged to validate XHTML for the generated guides before commiting your changes by running bundle exec rake validate_guides in the railties directory.
  • Edge guides can be consulted online. That website is generated periodically from docrails.

2 What to Contribute?

  • We need authors, editors, proofreaders, and translators. Adding a single paragraph of quality content to a guide is a good way to get started.
  • The easiest way to start is by improving an existing guide:
    • Improve the structure to make it more coherent.
    • Add missing information.
    • Correct any factual errors.
    • Fix typos or improve style.
    • Bring it up to date with the latest Edge Rails.
  • We’re also open to suggestions for entire new guides:
    • Contact lifo or fxn to get your idea approved. See the Contact section below.
    • If you’re the main author on a significant guide, you’re eligible for the prizes.

3 How is the process?

  • The preferred way to contribute is to commit to docrails directly.
  • A new guide is only edited by its author until finished though. In that case feedback can be given in its LH ticket.
  • If you are writing a new guide freely commit to docrails partial work and ping lifo or fxn when done with a first draft.
  • Guides reviewers will then provide feedback, some of it possibly in form of direct commits to agilize the process.
  • Eventually the guide will be approved and added to the index.

4 Prizes

For each completed guide, the lead contributor will receive all of the following prizes:

  • $200 from Caboose Rails Documentation Project.
  • 1 year of GitHub Micro account worth $84.
  • 1 year of RPM Basic (Production performance management) for up to 10 hosts worth 12 months x $40 per host x 10 hosts = $4800. And also, savings of $45 per host per month over list price to upgrade to advanced product.

5 Rules

  • Guides are licensed under a Creative Commons Attribution-Share Alike 3.0 License.
  • If you’re not sure whether a guide is actively being worked on, stop by IRC and ask.
  • If the same guide writer wants to write multiple guides, that’s ideally the situation we’d love to be in! However, that guide writer will only receive the cash prize for all the subsequent guides (and not the GitHub or RPM prizes).
  • Our review team will have the final say on whether the guide is complete and of good enough quality.

All authors should read and follow the Rails Guides Conventions and the Rails API Documentation Conventions.

6 Translations

The translation effort for the Rails Guides is just getting underway. We know about projects to translate the Guides into Spanish, Portuguese, Polish, and French. For more details or to get involved see the Translating Rails Guides page.

7 Mailing List

Ruby on Rails: Documentation is the mailing list for all the guides/documentation related discussions.

8 Contact

  • IRC : #docrails channel in irc.freenode.net
  • Twitter: @docrails, @lifo, @fxn
  • Email : pratiknaik aT gmail, fxn aT hashref dot com

Feedback

You're encouraged to help in keeping the quality of this guide.

If you see any typos or factual errors you are confident to patch, please clone docrails and push the change yourself. That branch of Rails has public write access. Commits are still reviewed, but that happens after you've submitted your contribution. docrails is cross-merged with master periodically.

You may also find incomplete content, or stuff that is not up to date. Please do add any missing documentation for master. Check the Ruby on Rails Guides Guidelines for style and conventions.

Issues may also be reported in Github.

And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome in the rubyonrails-docs mailing list.