4 ms·

The "Under the hood" visualization is awesome. I think more projects need to take the time to communicate details like this (without just big blobs of text or l

by akumpf 11y ago

The "Under the hood" visualization is awesome. I think more projects need to take the time to communicate details like this (without just big blobs of text or links to big piles of source code without a high-level overview). cheers! Edit: link directly to the diagram here -- http://www.deepstream.io/#segment-diagram http://www.deepstream.io/#segment-diagram

amelius 11y ago
Personally, I think the time spent on such visualizations is better spent on proper documentation, which is often inadequate. And by proper documentation, I don't mean one sentence per function. Also more useful, I think, is to enhance the documentation with comments for feedback or general user discussions. In that case, if the documentation is lacking, at least the user base can educate itself. Just my personal opinion.
- stingraycharles 11y ago
  A picture tells a thousand words. If anything, most opensource projects fail to do proper marketing. This a great counterexample. Having said that, they of course aren't mutually exclusive, but I can see both sides of the argument.
  - amelius 11y ago
    > If anything, most opensource projects fail to do proper marketing. Can you explain why opensource projects need such visual marketing? Shouldn't we choose the tools which are simply better in a technical sense, rather than the tools which have the flashiest pictures?
    - nmcfarl 11y ago
      Not the parent. But I can't count the number of times I've gone to an open-source project and couldn't even figure out what it did. And I don't consider that to be the lowest bar – any project that wants to get decent adoption should not only tell me what it does, but tell me why I should use it and not it competition. And do both of these things without me having to read the source code. Just this week - well perhaps last - I was at the homepage of some new language – and I couldn't find any of this nor a code example. This might be a technically fantastic language but if they don't communicate that adoption is going to suffer - and when it comes to communicating pictures have a place.
      - amelius 11y ago
        I can't remember seeing gnu.org showing flashy pictures back in the 90s, yet they had massive adoption.
        retbull 11y ago
        It had word of mouth and was the only free implementation of an OS that ran ok. Now there are 50,000 tools all free and no one hears what anyone says with all the noise.
    - goldbrick 11y ago
      Ouch, blatant false dichotomy.
      - amelius 11y ago
        Wrong. Marketing is all about convincing, nothing more. Have you ever heard somebody say "I prefer product X because it has such good marketing"?
        victorhooi 11y ago
        I think you're doing a disservice to marketing. Whilst I think a lot of it is just made-up hocus pocus as much as the next engineer =), how you present something is important. It's like being a genius inside your head, not not being able to express yourself. Ultimately, if you combine a good technical foundation with solid communication, you have a winning combination. Like it it not, that's how the world works. Nobody cares if you have great code and awesome tests, if you have poorly written documentation and you can't tell somebody what you do in a few sentences. Don't underestimate how difficult it is to get these last two right.
        amelius 11y ago
        But in this case, communication is not to random people but to fellow engineers. I've never heard anybody complain about the graphical communication of gnu.org, yet everybody seems to have been using the gnu C compiler for the last decades. Just an example. Finally, have a good look at that picture: http://www.deepstream.io/#segment-diagram http://www.deepstream.io/#segment-diagram And be honest, what does that tell you as an engineer? And what would you take from it as a "random person"? Is that what you call "solid communication"?
- pgsandstrom 11y ago
  Perhaps the persons making the flashy images and the persons writing the documentation are not the same.
  - intellent 11y ago
    But their salary source may be. Complicated world.

by akumpf 11y ago

amelius 11y ago

Personally, I think the time spent on such visualizations is better spent on proper documentation, which is often inadequate. And by proper documentation, I don't mean one sentence per function. Also more useful, I think, is to enhance the documentation with comments for feedback or general user discussions. In that case, if the documentation is lacking, at least the user base can educate itself. Just my personal opinion.

stingraycharles 11y ago
A picture tells a thousand words. If anything, most opensource projects fail to do proper marketing. This a great counterexample. Having said that, they of course aren't mutually exclusive, but I can see both sides of the argument.
- amelius 11y ago
  > If anything, most opensource projects fail to do proper marketing. Can you explain why opensource projects need such visual marketing? Shouldn't we choose the tools which are simply better in a technical sense, rather than the tools which have the flashiest pictures?
  - nmcfarl 11y ago
    Not the parent. But I can't count the number of times I've gone to an open-source project and couldn't even figure out what it did. And I don't consider that to be the lowest bar – any project that wants to get decent adoption should not only tell me what it does, but tell me why I should use it and not it competition. And do both of these things without me having to read the source code. Just this week - well perhaps last - I was at the homepage of some new language – and I couldn't find any of this nor a code example. This might be a technically fantastic language but if they don't communicate that adoption is going to suffer - and when it comes to communicating pictures have a place.
    - amelius 11y ago
      I can't remember seeing gnu.org showing flashy pictures back in the 90s, yet they had massive adoption.
      - retbull 11y ago
        It had word of mouth and was the only free implementation of an OS that ran ok. Now there are 50,000 tools all free and no one hears what anyone says with all the noise.
  - goldbrick 11y ago
    Ouch, blatant false dichotomy.
    - amelius 11y ago
      Wrong. Marketing is all about convincing, nothing more. Have you ever heard somebody say "I prefer product X because it has such good marketing"?
      - victorhooi 11y ago
        I think you're doing a disservice to marketing. Whilst I think a lot of it is just made-up hocus pocus as much as the next engineer =), how you present something is important. It's like being a genius inside your head, not not being able to express yourself. Ultimately, if you combine a good technical foundation with solid communication, you have a winning combination. Like it it not, that's how the world works. Nobody cares if you have great code and awesome tests, if you have poorly written documentation and you can't tell somebody what you do in a few sentences. Don't underestimate how difficult it is to get these last two right.
        amelius 11y ago
        But in this case, communication is not to random people but to fellow engineers. I've never heard anybody complain about the graphical communication of gnu.org, yet everybody seems to have been using the gnu C compiler for the last decades. Just an example. Finally, have a good look at that picture: http://www.deepstream.io/#segment-diagram http://www.deepstream.io/#segment-diagram And be honest, what does that tell you as an engineer? And what would you take from it as a "random person"? Is that what you call "solid communication"?
pgsandstrom 11y ago
Perhaps the persons making the flashy images and the persons writing the documentation are not the same.
- intellent 11y ago
  But their salary source may be. Complicated world.