I think reduction of friction can be beneficial here, elixir for example integrates documentation and tests - so you write you examples and tests right there, y

I think reduction of friction can be beneficial here, elixir for example integrates documentation and tests - so you write you examples and tests right there, you can write gnarly tests with regular testing suite, but giving documentation code value I think increases inherent value of writing documentation for developers.