News for hackers. Stuff that matters.
Re:Name It, and They Will Come by coldtea on Monday March 25, 2019 @05:35PM (#19486948)
>I honestly don't understand what this post is trying to say.

It says that most users wont try hard enough to understand a post, and instead comment like people are doing in this thread.

(It also suggests to try and give name to what you've built, and and try and weave it into an explicit narrative, to help people understand it and give more focused responses).

Re:Name It, and They Will Come by Deimorz on Monday March 25, 2019 @06:14PM (#19487224)
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?

Re:Name It, and They Will Come by btown on Monday March 25, 2019 @06:36PM (#19487389)
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 :)

Re:Name It, and They Will Come by sandinmyjoints on Tuesday March 26, 2019 @11:03AM (#19492467)
> 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!

Re:Name It, and They Will Come by btown on Wednesday March 27, 2019 @10:50AM (#19501340)
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.
Re:Name It, and They Will Come by Benjammer on Monday March 25, 2019 @06:23PM (#19487297)
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.
Re:Name It, and They Will Come by acemarke on Monday March 25, 2019 @07:01PM (#19487575)
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

[1] https://egghead.io/courses/getting-started-with-redux

[2] https://github.com/reduxjs/redux/issues/3313

Re:Name It, and They Will Come by platz on Monday March 25, 2019 @10:44PM (#19488863)
"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."

Re:Name It, and They Will Come by baddox on Monday March 25, 2019 @07:01PM (#19487585)
Dan doesn't say this, and I don't want to put words in his mouth, but the point I take away from this isn't that people are lazy and don't want to dive deep on a new idea, but instead that people are not obligated to discuss and give you exactly the type of feedback you want.

Even if your idea makes it to the top of HN, people are completely free to discuss ancillary topics or give feedback on areas you aren't interested in (like the coding style or design of the blog post).

And Dan proposes a solution. The solution isn't to decry the low quality of online discourse, or call people lazy, or use moderators to force people onto specific topics. The solution is to tell a story that people are interested in.

Re:Name It, and They Will Come by coldtea on Tuesday March 26, 2019 @03:50AM (#19489924)
>but instead that people are not obligated to discuss and give you exactly the type of feedback you want.

That we knew already though. It's a free country, and everything.

And I'm not sure his examples with the comments diverting into "landing pages" and such are meant in a good light of those making such comments.

Re:Name It, and They Will Come by Vinnl on Monday March 25, 2019 @05:39PM (#19486980)
If that's the case, then it appears that the suggested solution -telling a story- doesn't work...
Re:Name It, and They Will Come by adventured on Monday March 25, 2019 @06:56PM (#19487537)
Telling a story is the only solution that works. You either tell your story, over and over and over again until you can't stand to hear it, or you disappear into the noise. You pound the story home, or your competition will and they'll take up that mind share. There are many ways to tell and disseminate a story, that's the primary variable in successful products, not whether there's a story at all.
Re:Name It, and They Will Come by coldtea on Monday March 25, 2019 @05:39PM (#19486986)
Worked for many. Few things work for all people. Some need more time, others never get it.

What's important is if it's better than the baseline of not doing what he suggests.

Re:Name It, and They Will Come by ValleyOfTheMtns on Monday March 25, 2019 @11:48PM (#19489156)
So he should've named the naming problem.

Wait, is that what it's called? The Naming Problem?

Re:Name It, and They Will Come by cben on Monday April 01, 2019 @01:48PM (#19545985)
I think "Name it and they will come" is now a pretty good quotable name for the Naming / storytelling Solution.
Re:Name It, and They Will Come by aliswe on Tuesday March 26, 2019 @02:50AM (#19489738)
In all fairness, at least he told the story!