4 ms·

I agree, it is simply astounding that the entire thread is filled with praising the presentation style which only gets in the way of the user. Anytime there is

I agree, it is simply astounding that the entire thread is filled with praising the presentation style which only gets in the way of the user. Anytime there is a need to add effects, animations, snazzy things - question ruthlessly as to why is it needed. Then after justifying it, ask again. This is what good documentation looks like: https://golang.org/pkg/ https://golang.org/pkg/ And this: https://www.mpfr.org/mpfr-current/mpfr.html https://www.mpfr.org/mpfr-current/mpfr.html

josephwegner 7y ago
But this isn't documentation. This is a tutorial, in which progression and transitioning between steps is a fundamental part of the content. Representing that transition via animations is not inappropriate.
- marmada 7y ago
  It looks cool, but it is inappropriate because it wastes time since the transitions take time.
  - Silhouette 7y ago
    Do they take more time than repeating the same 10 or 20 lines of code with slight changes every couple of paragraphs, and having the reader try to figure out what changed since the last 4 times they read almost the same code?
jsjohnst 7y ago
You felt so passionately that you needed to say the same thing three times? This isn’t documentation, think of it more like a slide deck or tutorial. If it’s not your cup of tea, read the source material on Github or look elsewhere for the knowledge. While I somewhat agree with you on it’s a bit overkill, harping on that point repetitively is pointless.
- spectramax 7y ago
  Documentation, presentation, etc. - fundamentally, it is presenting sequential information to the user. And yes, I will say it again, this is NOT the way to do presentations. This is the programming presentation equivalent of designer things like this: https://www.ibm.com/plex/ https://www.ibm.com/plex/ Absolutely dreadful. But, thanks for the insight and advice about harping on something that I feel passionate about.
  - scarlet_lovah 7y ago
    > thanks for the insight and advice about harping on something that I feel passionate about. Given they are helping you out by pointing out a situation where you're being a bit obtuse and socially awkward (and thus helping you avoid similar situations in the future), I'd think that's pretty good. =)

josephwegner 7y ago

But this isn't documentation. This is a tutorial, in which progression and transitioning between steps is a fundamental part of the content. Representing that transition via animations is not inappropriate.

marmada 7y ago
It looks cool, but it is inappropriate because it wastes time since the transitions take time.
- Silhouette 7y ago
  Do they take more time than repeating the same 10 or 20 lines of code with slight changes every couple of paragraphs, and having the reader try to figure out what changed since the last 4 times they read almost the same code?

jsjohnst 7y ago

You felt so passionately that you needed to say the same thing three times? This isn’t documentation, think of it more like a slide deck or tutorial. If it’s not your cup of tea, read the source material on Github or look elsewhere for the knowledge. While I somewhat agree with you on it’s a bit overkill, harping on that point repetitively is pointless.

spectramax 7y ago
Documentation, presentation, etc. - fundamentally, it is presenting sequential information to the user. And yes, I will say it again, this is NOT the way to do presentations. This is the programming presentation equivalent of designer things like this: https://www.ibm.com/plex/ https://www.ibm.com/plex/ Absolutely dreadful. But, thanks for the insight and advice about harping on something that I feel passionate about.
- scarlet_lovah 7y ago
  > thanks for the insight and advice about harping on something that I feel passionate about. Given they are helping you out by pointing out a situation where you're being a bit obtuse and socially awkward (and thus helping you avoid similar situations in the future), I'd think that's pretty good. =)