Don't write like this. Respect your readers and help them comprehend. Expand acronyms as early as you can, ideally at the first mention.
The most recent guideline we added says: "Please don't complain about website formatting, back-button breakage, and similar annoyances. They're too common to be interesting." I suppose that complaints about writing style fall under the same umbrella.
Not that these things don't matter (when helping people with their pieces for HN I always tell them to define jargon at point of introduction), but they matter much less than the overall specific topic and much less than the attention they end up getting. So they're basically like weeds that grow and choke out the flowers.
(This is not a personal criticism—of course you didn't mean to have this effect.)
https://news.ycombinator.com/newsguidelines.html
[1] https://hn.algolia.com/?dateRange=all&page=0&prefix=true&sor...
I found the article quite good, and if you had genuinely been motivated to engage with the content you could have highlighted the acronym and searched for it. There is a wealth of good info for "CRDTs" that comes up on the first page of Google, Bing or DDG.
Does the acronym actually illuminate what they are or how they function? I submit to you that it probably doesn't.
It's called the link. All an author has to do is link the first instance of an acronym or piece of jargon to some authoritative description, and you get the best of both worlds: readers familiar with e.g. CRDTs[0] can just keep reading, and the rest can click the link and find out.
[0]: https://en.wikipedia.org/wiki/Conflict-free_replicated_data_...
It is especially useful when writing a technical document that utilizes multiple products/stacks/terms. Creating links to quality sources for those items gives someone new to the content a good source to go deeper into those pieces while allowing me to focus the article on the specific aspect I'm writing about.
Conflict-free Replicated Data Types (<a href="...">CRDT</a>)
A lot of people seem to be questioning why you'd need this when you could just provide a full link. Personally I read a lot of technical documentation and having acronyms written out in full would almost always be enough. Otherwise the whole document is likely over my head, or it's just a bad acronym.
Hypertext is great, links are practically free, I encourage authors to be liberal in applying them.
The same arguments for and against using libraries apply here, and it's up to the author which works best for their piece.
Just like libraries, sometimes it is and sometimes it isn't the best approach.
For example, in a "How to do $BASIC_THING in python" article, putting an intro of "This is what a variable is" may not be a bad idea. Meanwhile, in a "Writing an operating system from scratch in an esolang I wrote" article, maybe you'd be better off linking to previous blog posts or other resources.
Obviously these are both extreme examples, but I think it's still a valid view.
Anyway, blog author here - sorry I didn't explain CRDTs earlier in the piece. It didn't occur to me that people would be confused.
It never ceases to amaze me how many websites for restaurants or whatever neglect to mention basic things like what state (and country) they're in. Even newspaper web sites assume that we know that the "Chronicle" or the "Ledger" or whatever generic name is the local paper for East Bumblefuck.
Which they can easily provide themselves.
> If everything is written with jargon and abbreviations with no context [...]
It is not, for the intended audience.
The video also gives good context for the article, even for a beginner to the topic.
I read the title, wondered what CRDT was, and started reading. In the back of my mind I was wondering what CRDT was, but reading the article felt like I was going on a journey. Every term that needed to be defined was defined. Finally, when CRDT was mentioned in the article, it was immediately defined.
I generally agree that throwing acronyms around without defining them is not fair to the reader, but I don't think this article did that at all.
Whenever I see this writing style, such that I cannot find a thesis in the first two paragraphs, I almost universally discard the writing as a waste of time.
> I've spent the last decade working on OT, and have always thought it was the right way to implement a collaborative editor. Then something amazing happened.
Instead, we get this:
> I saw Martin Kleppmann’s talk a few weeks ago about CRDTs, and I felt a deep sense of despair. Maybe all the work I’ve been doing for the past decade won’t be part of the future after all, because Martin’s work on CRDTs will supersede it. Its really good.
That seems like the opposite of burying the lede. The main point of the story is _not_ that CRDT stands for Conflict-free Replicated Data Type, it's that the author now favors CRDTs over OT for collaborative editors.
That can be seen by glancing at the comments on this page.
Mods, can we expand the acronym in the title of this submission please?
I mean, if SLR's became DSLR's... I just assume any "D" means we're digital now! :)
This is way over the top.
I thought the author did an amazing job of discussing a highly technical topic in a very approachable way. Every blog on HN should aspire to write like this! It was so good it got me reading other posts even.
Yes, it would have been nice for us non- domain experts if the author had done the classic "Conflict-free replicated data type (CRDT)" thing, but you can easily just say that, ya know? "Hey, it would be helpful if you expanded CRDT early on."
Engineers, when talking about technical concepts with acronyms, always expand them for the first time to your readers!
In contrast, I like way more a different approach on explaining (mostly see it on Cyrillic forums) -- instead of guiding you by hand, they just give you clues where to look for. That way, knowledge givers are way more approachable, because it costs them very little to chat back something like "look for CRDT", than go into in-depth explaining. In the end -- there's way more information, and from top experts in the fields.
I’m a little embarrassed to admit I didn’t even notice.
I, for one, am grateful that you took the time to write it.
Anyway, I've updated the introductory paragraph to make it more clear.
Spelling out "Conflict-free replicated data type" doesn't really help beginners all that much and non-beginners will just use "CRDT" anyways.
We don't need every article about the web to spell out HTTP right? I don't get why the author is getting beat up just because his free content isn't convenient enough.