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

Ryan Briones ryan.briones at brionesandco.com
Fri Nov 6 17:27:40 EST 2009

This sounds pretty cool. Are there any ideas or examples of how features
would get turned into end user documentation? My first thought is something
RDoc like would go in the free-form user story area... I'd certainly like to
help as time permitted. I'd definitely like to be more informed of rspec

On Fri, Nov 6, 2009 at 7:49 AM, David Chelimsky <dchelimsky at gmail.com>wrote:

> 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.
> Cheers,
> David
> [1] http://wiki.github.com/aslakhellesoy/cucumber
> [2] http://github.com/aslakhellesoy/cucumber/tree/master/features/
> _______________________________________________
> rspec-devel mailing list
> rspec-devel at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-devel

Ryan Carmelo Briones
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://rubyforge.org/pipermail/rspec-users/attachments/20091106/a0bd423c/attachment.html>

More information about the rspec-users mailing list