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

Matt Wynne matt at mattwynne.net
Wed Jan 6 19:53:14 EST 2010

On 5 Jan 2010, at 12:17, Matt Patterson wrote:

> On 9 Nov 2009, at 22:03, Matt Wynne wrote:
>> 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.
> I've been looking at the documentation again recently, and I'd be  
> happy to start work on this, particularly if Matt W is wanting to  
> look at the cucumber end since he's just up the road from me.
> I'm very keen on the executable documentation aspects of this, and I  
> did a whole load of work back in 2008 on this kind of stuff using  
> RSpec, so I've got a bit of history here :-)

Great. I think it's time we really started dogfooding cucumber in  
terms of producing executable documentation. The features for Cucumber  
itself could do with some housekeeping, but right now the focus there  
is on the code, so RSpec seems like a nice place to work on this from.

I would like to see us try to build a flat HTML website (or PDF  
reference book) from rspec's features directory which could be used as  
reference by a new or curious user. As David says, I think we could  
drive out a bunch of really nice features from Cucumber to help make  
it much easier to build and maintain large suites of features.

So what's the first step? A pint or two at the Reliance perhaps Mr  


+447974 430184

More information about the rspec-users mailing list