Hacker News Reader

Hacker News

Comment by spectramax | Hacker News Reader

Parent Full thread

spectramax

Please don't perpetuate this type of animated presentation style. Why?

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/

View on HN

Boo - this is clearly excellent work by someone with both engineering and design skills. If no-one pushes the envelope then what a sad and boring world we would end up in.

It’s the best presentation for this style of content that I’ve ever seen. Having a description of what’s going on with a particular code block, plus highlighting the relevant parts, and moving that highlight or swapping out specific parts of it as I go through the content made it much faster for me to grasp what was important and what changed between blocks than would have been the case if the author used traditional static sections of code. This isn’t documentation, it’s a follow-along tutorial, and for that purpose this presentation style is 100% appropriate.

I think static documentation (your link) is a different use case than an interactive tutorial (not documentation). I didn't find the presentation horrible, but it's likely just looking nice and perfect on my computer hooked up to big monitors, and not on a phone or something....

I think everyone is saying that but presentation or documentation is essentially presenting sequential information to the user, whether it is a word document, a slide deck or a scrolling html page.

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".

You're dismissing scrolling as if it doesn't do anything but when I scroll I can see the code at a point in time as opposed to a point in space.

That’s precisely the problem - if both sides were moving together, in time it would be a slide deck, in space it would be a scrolling document. Here, we have the left and right side, changing in time and space, respectively, and burdening the user with cognitive dissonance.

if both sides were moving together, in time it would be a slide deck, in space it would be a scrolling document

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.

Exactly. This presentation style made it much easier for me to see what was being added to the code. I don't like having to continually scan different blocks of code to see what changed, and try to make sense of how the changes fit in the bigger picture.

I don't like having to continually scan different blocks of code to see what changed, and try to make sense of how the changes fit in the bigger picture.

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 do agree with you. I found it amazing to look at, but not very usable if you just wanna look at the code.

documentation =/= presentation

I love it...

Reply on news.ycombinator.com