by NAR8789 on 1/9/22, 8:52 AM with 7 comments
by fishtoaster on 1/11/22, 1:15 AM
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)