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

Rodrigo Rosenfeld Rosas lbocseg at yahoo.com.br
Sat Nov 7 08:15:48 EST 2009

David Chelimsky escreveu:
> Hi all,
> describe "RSpec's documentation" do
>   it "should be helpful"
>   it "should be maintainable"
> end
> 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 
> problems.
> * 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.
Hi David, it is awesome that you are concerned about improving Rspec 

Although I have no time currently to coordinate/drive the effort, and 
I'm not even skilled enough yet, I would be happy to contribute to 
documentation when I get some time, slowly...

I really liked the docrails project and it was really simple to 
contribute to Rails documentation using their model. Maybe it could be 
another way of improving Rspec's documentation. Although I like the idea 
of using some kind of wiki, I simple don't like the Github's wiki... I 
think they are a bit polluted...

It would be good if the Rspec site's content were hosted on Github, and 
there was a fork with open access for who wants to contribute, as it 
happens on railsdoc, and then, from time to time, someone could take a 
look at the changes and merge with main repository.

There are some mispelled words on Rspec site that could easily be 
corrected that way... And I think we should mantain Rspec site, 
improving its documentation instead of a one pager that links to 
Github's wiki...

Something like Rails Guides would also be awesome (like the tutorials 
you've proposed).

What do you think?

Best Regards,

Faça ligações para outros computadores com o novo Yahoo! Messenger 

More information about the rspec-users mailing list