Since no one wants to write the documentation, the simplest solution would be to let everyone write documentation, without noticing…

Normal documentation:

An Organisation is a firm or school that has an 
address(required) and can have users as members.

Pragmatig documentation with examples:

Organisation:
- requires an address
  organisation.address
- can have users as members
  organisation.members << User

Test:

describe Organisation do
  it "requires an address" do
    @organisation.should_not be_valid?
    @organisation.address = Address.new
    @organisation.should be_valid
  end

  it "can have users as members" do
    @organisation.should be_valid
    @organisation.members << User.new
    @organisation.should be_valid
  end
end
#before :each omitted

With the help of some spec -f or agiledox magic, we can extract:

An Organisation:
- requires an address
- can have users as members

looks familliar ?

I prefer this kind of testing, since it does not generate so many 3-liners(2(do/end)+1) nor uses “it should” all the time, which makes it look more documentation-ish.

DISCLAIMER: This way of writing tests is not RSpec-pure in that it does not use ‘it should’ and has more than on assertion (should) per example.