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

Ryan Briones ryan.briones at brionesandco.com
Sun Nov 8 11:49:39 EST 2009

On Sat, Nov 7, 2009 at 9:31 PM, David Chelimsky <dchelimsky at gmail.com>wrote:

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

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

>> 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
> _______________________________________________
> 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-devel/attachments/20091108/f134dce4/attachment-0001.html>

More information about the rspec-devel mailing list