[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 
documentation.

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,

Rodrigo.
__________________________________________________
Faça ligações para outros computadores com o novo Yahoo! Messenger 
http://br.beta.messenger.yahoo.com/ 



More information about the rspec-users mailing list