diff options
Diffstat (limited to 'railties/guides')
| -rw-r--r-- | railties/guides/source/contribute.textile | 60 |
1 files changed, 38 insertions, 22 deletions
diff --git a/railties/guides/source/contribute.textile b/railties/guides/source/contribute.textile index 1da591d7b1..0b666c4f44 100644 --- a/railties/guides/source/contribute.textile +++ b/railties/guides/source/contribute.textile @@ -1,52 +1,68 @@ h2. Contribute to the Rails Guides -Rails guides aim to improve Rails documentation and make the barrier to entry as low as possible. We periodically publish a list of guides we want at "Rails Guides Lighthouse":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets?q=state%3Aavailable. You can choose the topic you like, submit the guide and win prizes. +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. You can track the overall effort at the "Rails Guides Lighthouse":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets. Our sponsors have contributed prizes for those who write an entire guide, but there are many other ways to contribute. endprologue. h3. How to contribute? -* Update the respective Lighthouse ticket stating that you will be working on the guide. -* Once your proposal is accepted, the ticket will be put in "taken" state. +* We have an open commit policy: anyone is welcome to contribute, but you'll need to ask for commit access. * PM lifo at "GitHub":http://github.om asking for "docrails":http://github.com/lifo/docrails commit access. -* Commit your guide under railties/guides/source directory. For example, Active Record Basics guide resides at railties/guides/source/active_record_basics.textile -* Put all the images under railties/guides/images directory, if any. -* Once the guide is complete, you should update the Lighthouse ticket with the same information and ask for it to be reviewed. - -h3. Guides format - -* Guides should be in Textile format. -* Sample guides format : "Active Record Associations":http://github.com/lifo/docrails/blob/3e56a3832415476fdd1cb963980d0ae390ac1ed3/railties/guides/source/association_basics.textile -* Sample guides output : "Active Record Associations":http://guides.rails.info/association_basics.html +* Guides are written in Textile, and reside at railties/guides/source in the docrails project. +* All images are in the railties/guides/images directory. +* Sample format : "Active Record Associations":http://github.com/lifo/docrails/blob/3e56a3832415476fdd1cb963980d0ae390ac1ed3/railties/guides/source/association_basics.textile +* Sample output : "Active Record Associations":http://guides.rails.info/association_basics.html +* You can build the Guides during testing by running railties/guides/rails_guides.rb. + +h3. 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 mikeg1a in IRC or via "email":mailto:MikeG1@larkfarm.com to get your idea approved +** If you're the main author on a significant guide, you're eligible for the prizes + +h3. How to Commit + +* If you have a small change or typo fix, just ask lifo for commit access and commit it to the project. +* If your change is more significant, post a patch or a message on Lighthouse, and commit after you get a +1 from lifo or mikeg1a. +* If the guide is already marked done, you should get a +1 before pushing your changes. +* Put [#<ticket number>] in your commit message to enable GitHub/Lighthouse integration. h3. Prizes -For each completed guide, the contributor will receive all of the following 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 a lot of money. +* 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 h3. Rules -* Guides are licensed under a Creative Commons Attribution-Noncommercial-Share Alike 3.0 License -* We don't want multiple people writing the same guide, hence we allow only one person to be actively writing a guide. However, if you're very interested, please update the Lighthouse ticket anyways. In case the first person backs off, we will contact you -* If there is no/very less activity from the potential guide writer after claiming the guide, we could possibly allocate that guide to another writer -* 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 +* Guides are licensed under a Creative Commons Attribution-Noncommercial-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 h3. Reviewers -These are the main folks who'll be reviewing your guides, so always listen to them: +These are the main reviewers and editors for the guides: * Hongli Lai * Mike Gunderloy * Pratik Naik * Xavier Noria -h3. Editing +All authors should read and follow the "Rails Guides Conventions":http://wiki.github.com/lifo/docrails/rails-guides-conventions and the "Rails API Documentation Conventions":http://wiki.github.com/lifo/docrails/rails-api-documentation-conventions. + +h3. Translations -To ensure consistent quality and structure, Mike Gunderloy will make a copy editing pass over each guide. To make this easier, all authors should read and follow the Rails Guides Conventions and the Rails API Documentation Conventions. +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":http://wiki.github.com/lifo/docrails/translating-rails-guides page. h3. IRC Channel @@ -56,6 +72,6 @@ h3. Contact If you have any questions or need any clarification, feel free to contact: -* IRC : lifo, nzkoz, mikeg1a in #rubyonrails or #rails-contrib +* IRC : lifo, mikeg1a, fxn, or FooBarWidget in #docrails * Email : pratiknaik aT gmail |