[rspec-devel] describe "RSpec's documentation" do

David Chelimsky dchelimsky at gmail.com
Fri Nov 6 07:49:10 EST 2009

Hi all,

describe "RSpec's documentation" do
   it "should be helpful"
   it "should be maintainable"

I've been wanting to improve RSpec's documentation situation for a  
long time, but my writing energies have been consumed by rspec itself  
and The RSpec Book for a longer time, and will continue to do so for  
the foreseeable future. So I'm going to need some help.

The problem to solve is that we have (at least) four sources of  
documentation, each of which moves at its own pace and has evolved in  
its meaning/place:

1. The RSpec code examples that ship with RSpec
2. The Cucumber features that ship with RSpec
3. The github wiki: http://wiki.github.com/dchelimsky/rspec
4. http://rspec.info

The model that Aslak and the Cucumber community has used has worked  
very well because it's a community effort, but there is still some  
duplication between what's on the wiki [1] and the Cucumber features/ 
scenarios that ship with Cucumber [2].

In the long run, what I'd like is the following:

* Cucumber features that ship with RSpec become the authoritative end- 
user documentation. This is something that anybody can contribute to  
with patches, as it's all in files that ship with RSpec. I'd also like  
to use such an effort to push the envelope on Cucumber features as  
executable documentation. I think that with a little bit of work we  
could use the features to generate a website with meaningful  
organization/navigation. Is anybody already doing that?
* RSpec code examples become a solid source of additional detailed  
documentation for those who want to either extend RSpec or debug  
* http://rspec.info becomes a one pager like http://cukes.info
* The github wiki becomes a community driven resource center with  
links to tutorials, blogs, matcher libraries, etc, etc

I welcome suggestions, but I really need volunteers volunteers! I'm  
not going to be able to spend much personal time on this, so if there  
are any among you who are willing to coordinate with me and drive the  
effort, I'd love to hear from you.


[1] http://wiki.github.com/aslakhellesoy/cucumber
[2] http://github.com/aslakhellesoy/cucumber/tree/master/features/

More information about the rspec-devel mailing list