[dekhn]

I have long advocated the idea that online tutorials should have unit tests: there should be a daily build that loads the tutorial, extracts the code bits, runs them, and reports a failure if a dependency broke the tutorial.

And those tutorials should have the ability to force rollbacks of minor point releases that break backwards compatibility.

Tutorials should be pinned to major point releases.

[supriyo-biswas]

I have designed a personal tutorial authoring system that does exactly this, forcing you to include expected outputs in your article, which act as unit tests.

However the idea kinda went nowhere as the main issue with writing tutorials is that you gotta compete with websites with poorly written, ad-riddled articles that are somehow ranked on top by Google; and furthermore the end is near for such tutorial websites anyway given the proliferation of ChatGPT/GPT4.

[sdenton4]

I used to work on Sage, a math super package, which used 'doc tests' - documentation strings contained executable examples with expected outputs, and the test systems would run them all and check that they worked.

[JimDabell]

Python has this built in:

https://docs.python.org/3/library/doctest.html

[miguelgrinberg]

Explain to me how you would apply this concept to a book. Or to a YouTube video.

I'm not unreasonable, I get that things have to change from time to time. I just think maintainers should think more carefully when they introduce breaking changes. The cost to them is very high!

[dekhn]

I agree entirely that maintainers should be more careful with breaking changes. Few things annoy me more than getting 99% of thew way into a project and then getting an error simply because somebody moved a function from one place to the other.

This is really just another instance of CADT, imho.

I can't help with books- and IMHO, this is why books are obsolete for internet technology. I used to be a big OReilly fan, but at some point, the books were worse than useless because none of the examples would work 10 years later. Now, examples don't work 1 year later!

[bluedino]

Books are like the ultimate "container". They are so tied to certain versions. I liked the books that came with CD's that included everything, even if they were almost immediately obsolete.

[ilyt]

That reminds me my history with Ruby. Got to the famous "blog in 15 minutes" tutorial, used the stuff that comes with OS, nothing worked, didn't touch ruby again till I had to.