4 ms·

Okay, but what does that mean in practice? Almost every project posted on HN already has a name and at least a short description of why it exists or what it's t

Okay, but what does that mean in practice? Almost every project posted on HN already has a name and at least a short description of why it exists or what it's trying to do (often in the title itself). They still get bikeshedded to hell, so obviously the name and story alone aren't enough. I see a ton of posts where people bicker specifically about the name or the story (half the comments are "is this actually an issue?"). The linked post spends the entire time describing the problem but only 4 tiny sentences on the solution. It's really not self-explanatory even though it treats it like it is. Was writing it this way intended to be some kind of meta-commentary that's just going over my head?

Benjammer 8y ago
I honestly think part of this is just Dan's writing style in general. When I read his posts I often get a sense of him wanting to try and explain ideas at a conceptual level and teach people how to think and apply the concepts themselves, rather than provide step by step instructions for anything. I am far from an avid Overreacted reader though, I just read what gets posted here, mostly.
- acemarke 8y ago
  Yep, this is absolutely the case. As an example, see the "Middleware" tutorial page in the Redux docs [0], which Dan wrote. It walks through the process of "how and why did we end up at the final middleware API?", by demonstrating several "failed" attempts at solving the problem of logging. The page itself is well-written, and definitely demonstrates Dan's standard teaching style. But, it's also true that it's not obvious from glancing at the page how to _use_ middleware, because that doesn't come until the "failed" attempts. Another good example is his "Redux tutorial" videos on Egghead [1], where he walks through basically building Redux as the process for teaching how to use it and how it works. For some people, that teaching style is great. For others, they just want to know _how_ to use something, not necessarily how it _works_ right now. (We're planning to revamp the Redux docs soon-ish [2], and I do plan to change the contents of that "Middleware" tutorial to be an actual explanation of how to _use_ middleware correctly, and then move the "why does it work this way?" explanation to a different section of the docs.) [0] https://redux.js.org/advanced/middleware https://redux.js.org/advanced/middleware [1] https://egghead.io/courses/getting-started-with-redux https://egghead.io/courses/getting-started-with-redux [2] https://github.com/reduxjs/redux/issues/3313 https://github.com/reduxjs/redux/issues/3313
btown 8y ago
I wish Dan (the OP) had gone into more detail on exactly what techniques one can use to tell a story, because this is exactly what he does - very well! - as one of the most prolific voices in the React (and perhaps all of frontend) community. My personal take: (1) Marketing shouldn't be an afterthought; it must be considered in the same way one would write code. Take a page from the folks who designed a custom website and icon for Heartbleed. To put it another way, think of "things that would distract someone from the main message" as "bugs" in your code. Certainly, some bugs need to be triaged before any launch. But they should all be triaged with open eyes and respect for the user experience. (2) Don't assume people know acronyms or even the basics of your niche. Talk about potential use cases. Walk someone through the naive way of doing things, a less naive way of doing things, and why your thing naturally evolves/iterates on those. Make separate "background" pages if you want. Then take all of that as you would an essay you're writing for a class, and reshape it - find a thesis statement, tie everything back to it. Your launch post/README is a persuasive essay on why your thing is good. Even the "getting started" details are part of that persuasion - if it's easy to use, that's part of what makes it good. Well-written technical documentation can be a joy when you are immersed in the excitement of the person who built it. And with any immersive experience, there are things that can take you out of it. Immerse people quickly and keep them there, and maybe, just maybe, they'll be curious enough to do background research on their own and engage with you on the merits of the project with context :)
- sandinmyjoints 8y ago
  > To put it another way, think of "things that would distract someone from the main message" as "bugs" in your code. This is the PR/communications industry. Once I understood this, and that a main message is one sentence at most -- a short phrase is even better -- interviews of people in politics made a lot more sense!
  - btown 8y ago
    Yep, the same way we write code and think “what are the implications of this function were called from a weird context,” so too do PR/communications folks “engineer” statements.
platz 8y ago
"If you, as an author, want to spark an intelligent discussion on your product than do just that, present the points you want to debate while allowing some freedom for that noise since it isn't always useless. Instead of: "Hey HN, I just wrote a badass new streaming protocol" and linking to the github source, specifically mention your concerns about continuing to rely on TCP for video streaming and the buffering lag it induces, link to a blog-ish thing which links to your source but frames a number of questions or doubts you have around your project if you, indeed, are at a loss and want to turn to the internet as a whole to try and solve them."

Benjammer 8y ago

I honestly think part of this is just Dan's writing style in general. When I read his posts I often get a sense of him wanting to try and explain ideas at a conceptual level and teach people how to think and apply the concepts themselves, rather than provide step by step instructions for anything. I am far from an avid Overreacted reader though, I just read what gets posted here, mostly.

acemarke 8y ago
Yep, this is absolutely the case. As an example, see the "Middleware" tutorial page in the Redux docs [0], which Dan wrote. It walks through the process of "how and why did we end up at the final middleware API?", by demonstrating several "failed" attempts at solving the problem of logging. The page itself is well-written, and definitely demonstrates Dan's standard teaching style. But, it's also true that it's not obvious from glancing at the page how to _use_ middleware, because that doesn't come until the "failed" attempts. Another good example is his "Redux tutorial" videos on Egghead [1], where he walks through basically building Redux as the process for teaching how to use it and how it works. For some people, that teaching style is great. For others, they just want to know _how_ to use something, not necessarily how it _works_ right now. (We're planning to revamp the Redux docs soon-ish [2], and I do plan to change the contents of that "Middleware" tutorial to be an actual explanation of how to _use_ middleware correctly, and then move the "why does it work this way?" explanation to a different section of the docs.) [0] https://redux.js.org/advanced/middleware https://redux.js.org/advanced/middleware [1] https://egghead.io/courses/getting-started-with-redux https://egghead.io/courses/getting-started-with-redux [2] https://github.com/reduxjs/redux/issues/3313 https://github.com/reduxjs/redux/issues/3313

btown 8y ago

I wish Dan (the OP) had gone into more detail on exactly what techniques one can use to tell a story, because this is exactly what he does - very well! - as one of the most prolific voices in the React (and perhaps all of frontend) community. My personal take: (1) Marketing shouldn't be an afterthought; it must be considered in the same way one would write code. Take a page from the folks who designed a custom website and icon for Heartbleed. To put it another way, think of "things that would distract someone from the main message" as "bugs" in your code. Certainly, some bugs need to be triaged before any launch. But they should all be triaged with open eyes and respect for the user experience. (2) Don't assume people know acronyms or even the basics of your niche. Talk about potential use cases. Walk someone through the naive way of doing things, a less naive way of doing things, and why your thing naturally evolves/iterates on those. Make separate "background" pages if you want. Then take all of that as you would an essay you're writing for a class, and reshape it - find a thesis statement, tie everything back to it. Your launch post/README is a persuasive essay on why your thing is good. Even the "getting started" details are part of that persuasion - if it's easy to use, that's part of what makes it good. Well-written technical documentation can be a joy when you are immersed in the excitement of the person who built it. And with any immersive experience, there are things that can take you out of it. Immerse people quickly and keep them there, and maybe, just maybe, they'll be curious enough to do background research on their own and engage with you on the merits of the project with context :)

sandinmyjoints 8y ago
> To put it another way, think of "things that would distract someone from the main message" as "bugs" in your code. This is the PR/communications industry. Once I understood this, and that a main message is one sentence at most -- a short phrase is even better -- interviews of people in politics made a lot more sense!
- btown 8y ago
  Yep, the same way we write code and think “what are the implications of this function were called from a weird context,” so too do PR/communications folks “engineer” statements.

platz 8y ago

"If you, as an author, want to spark an intelligent discussion on your product than do just that, present the points you want to debate while allowing some freedom for that noise since it isn't always useless. Instead of: "Hey HN, I just wrote a badass new streaming protocol" and linking to the github source, specifically mention your concerns about continuing to rely on TCP for video streaming and the buffering lag it induces, link to a blog-ish thing which links to your source but frames a number of questions or doubts you have around your project if you, indeed, are at a loss and want to turn to the internet as a whole to try and solve them."