rspec users - Nov 2009 - describe "RSpec's documentation" do

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/

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
internals.

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>

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/

On Fri, Nov 6, 2009 at 5:27 PM, Ryan Briones
<ryan.briones at brionesandco.com>wrote:
> 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
> internals.
>
Yes, we should definitely beef up the narratives in each feature. Then we
need to generate the output as HTML and, the tricky part, generate some
wrapper HTML to make a site out of the different pages.

As for internals, my goal for the Cucumber features is to provide an
executable set of documentation for end users to understand how to use
RSpec. Not so much to expose internals, which I think is better addressed in
the RSpec code examples themselves. Make sense?

>
> 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
>
> _______________________________________________
> rspec-devel mailing list
> rspec-devel at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://rubyforge.org/pipermail/rspec-users/attachments/20091107/c3a0e477/attachment.html>

On Sat, Nov 7, 2009 at 9:31 PM, David Chelimsky <dchelimsky at gmail.com>
wrote:
>
> As for internals, my goal for the Cucumber features is to provide an
> executable set of documentation for end users to understand how to use
> RSpec. Not so much to expose internals, which I think is better addressed
in
> the RSpec code examples themselves. Make sense?
I''m sorry David; it might be because I haven''t seen examples,
but
conceptually I don''t think this quite gels.  Some issues I have with
the idea:

1.) It''s trying to achieve too many goals at once.  Application
verification and documentation are not the same problem.  If you try
to do both with the exact same files, I believe both will suffer.

2.) It creates an unnecessary knowledge dependency.  People who are
brand new to RSpec cannot be expected to have proficiency with
Cucumber just to read the docs.  I understand that they don''t *have*
to execute the features, but if you don''t know Cucumber at all, trying
to wrap your head around the feature syntax will distract from the
part that''s important (understanding RSpec).

3.) The knowledge transfer would be inefficient, unclear, and
incomplete.  Too many concepts cannot be effectively communicated in a
"Given/When/Then" structure.  How do you explain the history and
philosophy of BDD in that syntax?  How do you explain the role of
"red, green, refactor" patterns within iterative RSpec development?
--Presuming you''ve figured out how to phrase that knowledge in a
Cucumber feature, how do you *execute* it?  And at that point what
have you gained?

Cucumber is great for many things.  I don''t believe it would be a
great documentation tool at a "primer" level.  If anyone can show that
it can not only be done, but be done *well* in a way that will make
inherent sense to newbies and speed up their learning of RSpec, I''d
stand corrected and support this wholeheartedly.   Otherwise, I''d
suggest separating concerns, and not try to integrate and educate at
the same time.

---Having said that, I''m interested in contributing to the (prose, not
Cucumber) documentation effort.


-- 
Have Fun,
   Steve Eley (sfeley at gmail.com)
   ESCAPE POD - The Science Fiction Podcast Magazine
   http://www.escapepod.org

David Chelimsky escreveu:
> ...
>
> As for internals, my goal for the Cucumber features is to provide an 
> executable set of documentation for end users to understand how to use 
> RSpec. Not so much to expose internals, which I think is better 
> addressed in the RSpec code examples themselves. Make sense?
Actually, I don''t like very much the idea of hiding the internals.
I''ve
spent too much time trying to figure out what happens in the internals 
so that I could integrate Rspec with Webrat and I still don''t
understand
a lot of things.

For instance, why can I use ''visit'' when I am testing an
expected
behavior, but cannot use ''redirected_to'' while both belongs to
Webrat::Session?

I think it helps a lot understanding what is happening on the internals. 
Some topics that could be approached on documentation:

- What happens on a describe/context/it/specify call?
- What is the load order when running tests? (talking more deeply about 
spec_helper.rb)
- How are database transactions dealt with in Rspec and the differences 
between before(:all) and before(:each) with respect to databases.
- What is the class (how is it created?) that we are writing code on? 
How are the expectations/matchers injected on classes and which classes?

I really think that knowing the internals would help a lot and save us 
many many time.

The syntax of Rspec should be simple so that reading the specs should be 
natural, but it doesn''t mean that we should abstract from what is 
happening in the internals...

Well, that is my opinion.

Regards,

Rodrigo.

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

On Sat, Nov 7, 2009 at 11:39 PM, Stephen Eley <sfeley at gmail.com> wrote:
> On Sat, Nov 7, 2009 at 9:31 PM, David Chelimsky <dchelimsky at
gmail.com>
> wrote:
> >
> > As for internals, my goal for the Cucumber features is to provide an
> > executable set of documentation for end users to understand how to use
> > RSpec. Not so much to expose internals, which I think is better
addressed
> in
> > the RSpec code examples themselves. Make sense?
>
> I''m sorry David; it might be because I haven''t seen
examples, but
> conceptually I don''t think this quite gels.  Some issues I have
with
> the idea:
>
> 1.) It''s trying to achieve too many goals at once.  Application
> verification and documentation are not the same problem.  If you try
> to do both with the exact same files, I believe both will suffer.
>
Executable documentation is what I''m after. If Cucumber is not giving
that
to us now, then I''d like to use this opportunity to push in that
direction.
The whole point is to bind the documentation to the code so that as the code
evolves, the documentation is less likely to stray from it.

>
> 2.) It creates an unnecessary knowledge dependency.  People who are
> brand new to RSpec cannot be expected to have proficiency with
> Cucumber just to read the docs.  I understand that they don''t
*have*
> to execute the features, but if you don''t know Cucumber at all,
trying
> to wrap your head around the feature syntax will distract from the
> part that''s important (understanding RSpec).
>
Have you looked at
http://github.com/dchelimsky/rspec/blob/master/features/before_and_after_blocks/before_and_after_blocks.feature,
for example? I don''t think Given/When/Then are going to confuse anybody
in
this case.

>
> 3.) The knowledge transfer would be inefficient, unclear, and
> incomplete.  Too many concepts cannot be effectively communicated in a
> "Given/When/Then" structure.  How do you explain the history and
> philosophy of BDD in that syntax?  How do you explain the role of
> "red, green, refactor" patterns within iterative RSpec
development?
> --Presuming you''ve figured out how to phrase that knowledge in a
> Cucumber feature, how do you *execute* it?  And at that point what
> have you gained?
>
That''s what the narrative area is for, in part. And where that is
inappropriate, we should have a way to build a website that integrates
cucumber pages with plain HTML pages. Something like webby with a plugin for
running the .feature files and storing the output as HTML pages. The
examples of what the code looks like should be executable.

> Cucumber is great for many things.  I don''t believe it would be a
> great documentation tool at a "primer" level.  If anyone can show
that
> it can not only be done, but be done *well* in a way that will make
> inherent sense to newbies and speed up their learning of RSpec,
I''d
> stand corrected and support this wholeheartedly.   Otherwise, I''d
> suggest separating concerns, and not try to integrate and educate at
> the same time.
>
> ---Having said that, I''m interested in contributing to the (prose,
not
> Cucumber) documentation effort.
>
Great. My goal is to have an integrated result, but that doesn''t mean
that
people can''t contribute to prose separately from scenarios.

--
> Have Fun,
>
I usually do :)

Cheers,
David

>   Steve Eley (sfeley at gmail.com)
>   ESCAPE POD - The Science Fiction Podcast Magazine
>   http://www.escapepod.org
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://rubyforge.org/pipermail/rspec-users/attachments/20091108/a698738f/attachment-0001.html>

On Sun, Nov 8, 2009 at 5:55 AM, Rodrigo Rosenfeld Rosas <
lbocseg at yahoo.com.br> wrote:
> David Chelimsky escreveu:
>
>>
>> As for internals, my goal for the Cucumber features is to provide an
>> executable set of documentation for end users to understand how to use
>> RSpec. Not so much to expose internals, which I think is better
addressed in
>> the RSpec code examples themselves. Make sense?
>>
>
> Actually, I don''t like very much the idea of hiding the internals.

I''m not saying hide them. I''m saying document them in a
different way.

> I''ve spent too much time trying to figure out what happens in the
internals
> so that I could integrate Rspec with Webrat and I still don''t
understand a
> lot of things.
>
> For instance, why can I use ''visit'' when I am testing an
expected behavior,
> but cannot use ''redirected_to'' while both belongs to
Webrat::Session?
>
> I think it helps a lot understanding what is happening on the internals.
> Some topics that could be approached on documentation:
>
> - What happens on a describe/context/it/specify call?
> - What is the load order when running tests? (talking more deeply about
> spec_helper.rb)
> - How are database transactions dealt with in Rspec and the differences
> between before(:all) and before(:each) with respect to databases.
> - What is the class (how is it created?) that we are writing code on? How
> are the expectations/matchers injected on classes and which classes?
>
> I really think that knowing the internals would help a lot and save us many
> many time.
>
> The syntax of Rspec should be simple so that reading the specs should be
> natural, but it doesn''t mean that we should abstract from what is
happening
> in the internals...
>
Separate, not abstract.

> Well, that is my opinion.

Thanks for sharing it. I think we can work towards this goal as well, but
I''d like to push this one further back as plan to make significant
changes
to internals in the next major version of rspec. We''ll roll that out
gradually (with alpha, beta, and candidate releases), but any time spent on
a big document-the-internals effort before then would be a waste.

Cheers,
David

> Regards,
>
> Rodrigo.
>
> __________________________________________________
> Fa?a liga??es para outros computadores com o novo Yahoo! Messenger
> http://br.beta.messenger.yahoo.com/
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://rubyforge.org/pipermail/rspec-users/attachments/20091108/50dddf16/attachment.html>

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

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 :-)

Matt


-- 
  Matt Patterson | Design & Code
  <matt at reprocessed org> | http://www.reprocessed.org/

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

cheers,
Matt

http://mattwynne.net
+447974 430184

On 7 Jan 2010, at 00:53, Matt Wynne wrote:
> On 5 Jan 2010, at 12:17, Matt Patterson wrote:
> 
>> 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
Patterson?
That sounds about right :-)

Matt


-- 
  Matt Patterson | Design & Code
  <matt at reprocessed.org> | http://www.reprocessed.org/