3 ms·

and yet in my experience most HNers and similar tech communities want all docs in plain text, tex, or very simple markdown suggest that Wikipedia would be bett

and yet in my experience most HNers and similar tech communities want all docs in plain text, tex, or very simple markdown suggest that Wikipedia would be better if it's physics articles had interactive simulations or that stack overflow's failed docs initiative should make room for working examples and get downvoted into oblivion

tomashubelbauer 7y ago
We've seen some interactive education projects on HN (the famous page on raytracing, the one where there's everything about curves, many audio-based projects) and they have had great reception. I think the reason why most devs still prefer plain-text resources over anything else is two-fold: interactive stuff tends to be less standard (because there isn't really a good standard for it) and harder to version than text, but also for interactive education/documentation tools to be accepted, they need to meet a certain high bar of quality, otherwise they are just eye-candy with insufficient value-add. When developing such tools, I believe there is a point of immersion after which they clearly become superior to text materials to most people including otherwise text-heavy devs, but if an author of such interactive tool fails to reach this level, their work is seen as a distraction, because you still need to refer elsewhere. Stack Overflow's documentation examples (as much as I really wished the initiative would succeed) were very far from reaching this bar. They were not organized well, lackluster and were not interactive enough either.
- maxheadroom 7y ago
  >I think the reason why most devs still prefer plain-text resources over anything else is... I think you missed a vital reason and that is portability and sharability. No one needs to install anything special to read or edit a text file. It's the digital equivalent of paper and pen when you think about it and that makes it a popular platform for everyone to be able to consume it. Plus, back when we were all old and dinosaurs roamed the Earth, the text file was the lightest/smallest way to transfer data (read: ideas) between computers. The practice/behaviour saturated the industry so much that many readmes of today are still on text files. Maybe there's a correlation to the real world, where we're definitely more apt to consume mediums that don't have superfluous data points than the words/ideas that they're meant to convey? Maybe I'm just talking out of my ass? Either way, plain-text resources are the easiest to create, share, and consume because there's almost a universality in the standard for text files (except the EOL and CRLF but that's more of an inconvenience than anything).
  - tomashubelbauer 7y ago
    This is what I meant by standardization but I used a wrong term. I completely agree with you. At the basis, there will always need to be plain text, which should result in a wide variety of viewers and editors becoming available. In order for interactive visualizations to succeed among software devs, they can't be a SaaS, they need to become a part of the plumbing.
SmellyGeekBoy 7y ago
It's almost as if they're aimed at completely different audiences!
- masklinn 7y ago
  HN on a phone is a miserable experience.
TeMPOraL 7y ago
Part of the reason is because that decouples the content from the presentation format. Give me a .txt, .md, or even a .tex file, and I can load it in my editor next to the code I'm working on, and I can efficiently jump around, search, and copy from it, all via a keyboard. At any point I can easily print it out and have a stab at it with a highlighter. Give me the super modern web documentation, and now I have to pick up the mouse, I have to install a tiling WM just to stay sane, I only have the most basic search available (which is broken half of the time because of bleeding-edge webdev bullshit), and if I try to print it (God forbid!), every page is 50% header and sidebar. Techies like plaintext because it's free of superfluous bullshit. It's efficient. It's flexible. As for interactive simulations, I'm all for them. I love the work of Bret Victor, or Nicky Case, or other stuff in the category of "explorable explanations". Those people do it well. But if it's not executed well, it's worse than not being done at all.

tomashubelbauer 7y ago

We've seen some interactive education projects on HN (the famous page on raytracing, the one where there's everything about curves, many audio-based projects) and they have had great reception. I think the reason why most devs still prefer plain-text resources over anything else is two-fold: interactive stuff tends to be less standard (because there isn't really a good standard for it) and harder to version than text, but also for interactive education/documentation tools to be accepted, they need to meet a certain high bar of quality, otherwise they are just eye-candy with insufficient value-add. When developing such tools, I believe there is a point of immersion after which they clearly become superior to text materials to most people including otherwise text-heavy devs, but if an author of such interactive tool fails to reach this level, their work is seen as a distraction, because you still need to refer elsewhere. Stack Overflow's documentation examples (as much as I really wished the initiative would succeed) were very far from reaching this bar. They were not organized well, lackluster and were not interactive enough either.

maxheadroom 7y ago
>I think the reason why most devs still prefer plain-text resources over anything else is... I think you missed a vital reason and that is portability and sharability. No one needs to install anything special to read or edit a text file. It's the digital equivalent of paper and pen when you think about it and that makes it a popular platform for everyone to be able to consume it. Plus, back when we were all old and dinosaurs roamed the Earth, the text file was the lightest/smallest way to transfer data (read: ideas) between computers. The practice/behaviour saturated the industry so much that many readmes of today are still on text files. Maybe there's a correlation to the real world, where we're definitely more apt to consume mediums that don't have superfluous data points than the words/ideas that they're meant to convey? Maybe I'm just talking out of my ass? Either way, plain-text resources are the easiest to create, share, and consume because there's almost a universality in the standard for text files (except the EOL and CRLF but that's more of an inconvenience than anything).
- tomashubelbauer 7y ago
  This is what I meant by standardization but I used a wrong term. I completely agree with you. At the basis, there will always need to be plain text, which should result in a wide variety of viewers and editors becoming available. In order for interactive visualizations to succeed among software devs, they can't be a SaaS, they need to become a part of the plumbing.

SmellyGeekBoy 7y ago

It's almost as if they're aimed at completely different audiences!

masklinn 7y ago
HN on a phone is a miserable experience.

TeMPOraL 7y ago

Part of the reason is because that decouples the content from the presentation format. Give me a .txt, .md, or even a .tex file, and I can load it in my editor next to the code I'm working on, and I can efficiently jump around, search, and copy from it, all via a keyboard. At any point I can easily print it out and have a stab at it with a highlighter. Give me the super modern web documentation, and now I have to pick up the mouse, I have to install a tiling WM just to stay sane, I only have the most basic search available (which is broken half of the time because of bleeding-edge webdev bullshit), and if I try to print it (God forbid!), every page is 50% header and sidebar. Techies like plaintext because it's free of superfluous bullshit. It's efficient. It's flexible. As for interactive simulations, I'm all for them. I love the work of Bret Victor, or Nicky Case, or other stuff in the category of "explorable explanations". Those people do it well. But if it's not executed well, it's worse than not being done at all.