[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"
> 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  and the Cucumber
> features/scenarios that ship with Cucumber .
> 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.
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
Something like Rails Guides would also be awesome (like the tutorials
What do you think?
Faça ligações para outros computadores com o novo Yahoo! Messenger
More information about the rspec-users