Tuesday, January 02, 2007

Rubinius Serial Interview: Episode III

A comment that seems to be coming up a lot is: "Where are the docs?". Let's detour briefly from testing and talk about docs (okay, it won't be a complete detour ...):

What plans do you have to get solid user and developer level docs for rubinius?

Wilson: In the near future, one of us will kick out a big shiny diagram of all of the moving parts of Rubinius. I like diagrams. Particularly shiny ones.

On the developer doc side of things, it would be helpful to know what people were looking for first. There are a number of things that need to be documented eventually, but spending time on pieces people aren't looking at yet is a waste.

People can use either the mailing list or the ticket system to make documentation requests. That would be helpful, I think.

Evan: I've been starting to think more about developer docs lately actually. I've begun to draw a diagram of how the majority of the components interact.

I'd love to start to get questions from people about how certain parts work so that I can begin to document those parts first.

A big knock against Ruby is that there's no spec for it. Charles Nutter has been trying to build one, but it's not there yet. How much does this hurt you? What are you doing to overcome it?

Wilson: I think the lack of a spec is OK. Specifying everything too early has a long track record of killing perfectly good languages. That being said, I think Ruby 1.8 is ready for one. There are now several implementations that can run real code, and the 'specs' from 'ri' only go so far.

I'm looking forward to working with Charles and the others on a spec. Until then, we're planning to just pit the various runtimes against each other, Thunderdome-style, as part of the test suite.

Evan: I agree with Wilson, currently no spec is not the end of the world. There seems to be a lot of movement toward formulating a spec for how the core functionality should perform. I'm fully committed to running rubinius against any and all specs for the core functionality that are available.

One of the things that I like about RSpec is it's ability to output specification docs. How does this feature play into rubinius' future with RSpec?

Wilson: I love this feature. The doc output is probably not detailed enough to be a spec in its own right, but it should make for some nice, readable developer documentation. The only drawback to RSpec for Rubinius at the moment is that it depends on rubygems, and that library will take some doing to get running under Rubinius, due to its large bag of tricks. It will come, but probably not this week. :)

Evan: My hope is that we can begin to use the specs as real documentation and verification of the system, ala perl 6's integrated documents and test runs. This provides people with a great insight into what parts work and don't without diving into the code.


Episode three of the rubinius Serial Interview is brought to you by: Spring Into Technical Writing. One of my favorite books about technical writing. Buy yourself a copy, then help document rubinius (or any other deserving project).

Previous episodes of the Serial Rubinius Interview are available here:

  • Episode 1, in which we talk about the rubinius community
  • Episode 2, in which we talk about cuby and testing tools

2 comments:

Anonymous said...

my understanding is that evan was able to get rubinius self-hosted last week. that's a great acomplishment, indeed.

Wilson Bilkovich said...

It was brought to my attention today that RSpec can run without RubyGems. Interesting. Heh.