describe "RSpec's documentation" do

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
6 messages Options
Reply | Threaded
Open this post in threaded view
|

describe "RSpec's documentation" do

David Chelimsky-2
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
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel
Reply | Threaded
Open this post in threaded view
|

Re: describe "RSpec's documentation" do

Ryan Carmelo Briones
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 <[hidden email]> 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
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel



--
Ryan Carmelo Briones

_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel
Reply | Threaded
Open this post in threaded view
|

Re: describe "RSpec's documentation" do

David Chelimsky-2
On Fri, Nov 6, 2009 at 5:27 PM, Ryan Briones <[hidden email]> 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 <[hidden email]> 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
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel



--
Ryan Carmelo Briones

_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel


_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel
Reply | Threaded
Open this post in threaded view
|

Re: describe "RSpec's documentation" do

Ryan Carmelo Briones

On Sat, Nov 7, 2009 at 9:31 PM, David Chelimsky <[hidden email]> wrote:
On Fri, Nov 6, 2009 at 5:27 PM, Ryan Briones <[hidden email]> 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?

Yes. Being more familiar with the internals was more for my own edification. ;)
 
 

On Fri, Nov 6, 2009 at 7:49 AM, David Chelimsky <[hidden email]> 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
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel



--
Ryan Carmelo Briones

_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel


_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel



--
Ryan Carmelo Briones

_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel
Reply | Threaded
Open this post in threaded view
|

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

Matt Patterson-4
In reply to this post by David Chelimsky-2
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/



_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel
Reply | Threaded
Open this post in threaded view
|

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

David Chelimsky-2
On Tue, Jan 5, 2010 at 6:17 AM, Matt Patterson <[hidden email]> 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 :-)

Hi Matt,

You mean you want to work on cukes for RSpec? If so, that would be great!

Cheers,
David

Matt


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



_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel


_______________________________________________
rspec-devel mailing list
[hidden email]
http://rubyforge.org/mailman/listinfo/rspec-devel