RSpec-2 was released with, admittedly, less than complete documentation. The new docs are a work in progress that need your help. It’s all open source, and anybody who can write Markdown or Cucumber can contribute to it. Here’s how:
You
Fork the git repo you of the rspec project to which you want to contribute docs, make additions/edits to appropriate files in the features directory, and submit pull requests.
Me
I review, tweak, and organize the contributions, merge them in, and then push them to http://relishapp.com.
Source repositories
With the exception of the front page, all of the docs are stored in the features directories of rspec repositories on github:
Relish
Relish is an application developed by Justin Ko and Matt Wynne to display Cucumber features for open and closed source projects. It is still fairly new and under regular development, so presentation, navigation, etc, are all improving as we go.
Cucumber and Markdown docs live in the features directory (and its subdirectories) in each project. There is a .nav file that sorts the navigation links. It’s pretty self-explanatory, and you probably won’t need to touch it. But now you know what it is.
Cukes
If you know what you’re doing with Cucumber, feel free to submit executable scenarios. Please make sure you run them and they pass against ruby-1.8.6, 1.8.7, 1.9.1, and 1.9.2. Bonus points for jruby and rbx.
Even if you don’t know what you’re doing with Cucumber, all of the Cucumber features have a narrative section at the top, which is plain text and not executed. Relish processes this section through Markdown, so it can be as expressive as you know how to make Markdown “speak.” Patches that add to this narrative are great, but so are patches that simply re-format them to make them more readable.
Pages
In addition to the Cucumber features, Relish supports pages using Markdown. Each project has a README file in the features directory which is displayed as the front page for that project. Each subdirectory below features can also have a README (optional), which would be displayed as the front page of that directory.
In addition to the README files, we can add arbitrary pages using Markdown as well.
Questions?
If you want to help and you’re not sure where to start, feel free to contact me via email to the rspec-users list or a github issue in the project you’re interested in contributing to.