To be honest, I find them pretty hard to read and unhelpful. If the four types of documentation are tutorials, how-to guides, concept discussion, and reference, these rspec-as-documentation docs occupy an uncomfortable position between how-to guides and reference: they're neither detailed enough to act as a reference, nor narrative enough to act as a guide to solving any problem. They're slower to parse quickly than a equivalent prose and more complex than an equivalent code sample with a description.
They probably offer some value - I suppose I'd rather have literate tests than not, but they should be in addition to proper documentation, not instead of.
(disclaimer: I only really interact with that one example - rspec on relish - and I may be conflating flaws in that example with flaws in the whole technique)
I interact with "Rspec as documentation" with some frequency when referring to the docs for rspec itself on Relish:
https://relishapp.com/rspec/rspec-core/docs/helper-methods/a...
To be honest, I find them pretty hard to read and unhelpful. If the four types of documentation are tutorials, how-to guides, concept discussion, and reference, these rspec-as-documentation docs occupy an uncomfortable position between how-to guides and reference: they're neither detailed enough to act as a reference, nor narrative enough to act as a guide to solving any problem. They're slower to parse quickly than a equivalent prose and more complex than an equivalent code sample with a description.
They probably offer some value - I suppose I'd rather have literate tests than not, but they should be in addition to proper documentation, not instead of.
(disclaimer: I only really interact with that one example - rspec on relish - and I may be conflating flaws in that example with flaws in the whole technique)