I interact with "Rspec as documentation" with some frequency when referring to the docs for rspec itself on Relish:<p><a href="https://relishapp.com/rspec/rspec-core/docs/helper-methods/arbitrary-helper-methods" rel="nofollow">https://relishapp.com/rspec/rspec-core/docs/helper-methods/a...</a><p>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.<p>They probably offer some value - I suppose I'd rather have literate tests than not, but they should be <i>in addition</i> to proper documentation, not <i>instead of</i>.<p>(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)