This is a lot more effective a medium for the content!

I even went ahead an set up a monthly donation to their open collective project [1] because it is so beautiful.

1: https://opencollective.com/code-surfer

1) Vertical layout is easier to scroll

2) Vertical layout puts the code blocks in-line to know where they belong in the text

3) Author's presentation style has animations that slow down user's ability to scan quickly

4) Scroll position determines the code block's visibility (!!! WTF)

5) Either have the entire page white or black. The contrast changes between reading the document and then reading the code tires the user

6) Scroll wheel feels highjacked because the left pane is static

I could go on and on. I strongly discourage people from using this type of documentation. Your users, will get tired of the novelty and when push comes to shove, they will want something like this:

https://golang.org/pkg/

Also, there is nothing interactive about it - I can't change code on the left side, nor can I do anything with the right side. It is just scrolling, I guess you can call that "interaction".

There is a fundamental difference between reference material, where only the final version is relevant, and tutorial material, where the evolution is also important. You keep making similar comments in this discussion where you compare this tutorial/exposition format to typical reference documentation, but they're solving different problems and reasonable assumptions in one case don't necessarily hold in the other.

In particular, presenting this sort of tutorial/exposition material as you suggest could make the document much longer, but worse, the reader would have to keep looking at almost the same code snippet and figuring out what changed at each step instead of having it demonstrated by the animation effect. That is a significant mental overhead, and it's a recurring pain point when teaching programming subjects that can be remedied by using something that actively shows the progression. I've used similar techniques where some example code evolves with simple animations in both presentations and private documentation, and it generally seems to be effective at communicating the intended ideas and well received by the target audience.

Indeed.

Visual diff tools were invented for a reason, and using a side-by-side layout with some sort of colour coding and some attempt to align equivalent code is now close to universal. No-one would suggest doing code reviews by printing out the last two versions of a source file and comparing them on paper any more.

In presenting tutorial material like this, IME the two most effective formats have been either something like that side-by-side diff, often with some extra annotations like chunky labelled arrows to highlight the specific areas or changes of interest, or something like the style here, with the changes at each step being highlighted and/or animated so it's easy to follow along. Both of these work for code but also other illustrations.

I hope not, because slow, meaningless animation makes me tired and something inside me wants escape that page. Also it affects scrolling, especially noticeable when I am scanning a text instead of reading - you might lose context (note how the presentation reacts on pressing "page-up" / "page-down"). Kindle and all e-reader hates animations[0][1] - any animations (they are just huge black holes for battery). IMHO any documentation SHOULD be able to printed out on paper and sorry - paper is not interactive.

However, I will warmly welcome some interaction in dedicated docs section but it would be great if it could be duplicated as a rich-text article.

[0]: Not saying about the reader mode in browsers (e.g. Firefox)

[1]: Please think also about people that are disabled or use VoiceOver/NarratorMode to be more productive / are just lazy to read text using their eyes :)

Unnecessary animations, fixed scrolling, and just useless "snazzy" aspects of user interface has no place in code documentation.

I hope this does not become the standard.