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).
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?
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 :)
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!
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
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."
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.
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.
What's important is if it's better than the baseline of not doing what he suggests.
Wait, is that what it's called? The Naming Problem?
On-topic bike-shedding would actually be an improvement.
I believe this happens most often with announcements that are legitimate news but kind of boring. The larger, generic topic is more interesting and it's sorta related, so it's more attractive to talk about that.
A possible solution: be more interesting. Tell a story.
Besides, I find that there's often/sometimes a big gap between understanding a concept (like bike shedding) on an abstract level compared to being able to relate and to it when it arises in practice (unless perhaps you've grasped in some special way). Telling various stories that exemplify such concept in a multitude of ways can reveal new facets of it.
> Let me insert one thing, which I'll bet you've noticed from talking to writers—is that most of the stuff that we think we're writing about in books is very difficult to talk about straight out. You know, question and answer. In some sense, it probably can't be talked about directly, and that's why people make up stories about it.
Or that's my interpretation of the article anyway.