This piece argues that bbt turns README examples into executable tests, so the docs become the spec and the test suite in one place - which is neat, assuming people actually keep the README up to date.
The “keep the README up to date” part is exactly where I’ve seen this fall over, unless you keep the examples tiny and stable.
Yeah, the only times I’ve seen this stick is when the README examples are treated like a public API: super small, and you’re ruthless about deleting anything that’s “nice to show” but not worth supporting. We ended up moving anything even slightly complex into a /examples folder and keeping the README as basically a thin index so the tests don’t turn into a documentation babysitting job.
Fair
