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

Matt Wynne matt at mattwynne.net
Mon Nov 9 17:03:18 EST 2009


On 6 Nov 2009, at 12:49, David Chelimsky wrote:

> 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?

+1

I had a little epiphany working on the wire protocol feature for  
cucumber[3]. We were trying to design the protocol via email and  
lighthouse ticket discussion, started using a wiki to document the  
desired protocol when I realised - why don't we just use the  
features!? I would like to see more people pushing Cucumber in this  
direction, and I think it would be interesting to consider adding mark- 
up to comments to allow us to build RDoc-style websites from a  
features folder.

> * 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/

[3]http://github.com/aslakhellesoy/cucumber/blob/master/features/wire_protocol.feature

I'm well behind this effort and would like to offer my help on the  
Cucumber end to make it possible to use the features to generate the  
user documentation - I think this would make a terrific use case for  
us to support.

cheers,
Matt

http://mattwynne.net
+447974 430184



More information about the rspec-users mailing list