15 ms·
It takes over 800 words, and several mentions of the CRDT acronym, before the acronym is expanded for the reader. Don't write like this. Respect your readers
by stblack 6y ago
It takes over 800 words, and several mentions of the CRDT acronym, before the acronym is expanded for the reader.
Don't write like this. Respect your readers and help them comprehend. Expand acronyms as early as you can, ideally at the first mention.
- samatman 6y agoAs I tirelessly mention whenever this comes up on HN, which is often: we have a specific technology that is designed precisely for this situation. 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_type https://en.wikipedia.org/wiki/Conflict-free_replicated_data_...
- thesuitonym 6y agoEven better, just use the abbr tag. It's well supported and doesn't rely on an outside source to tell your readers what you're talking about.
- JeremyBanks 6y agoMerely expanding an abbreviation is less useful than explaining it.
- dllthomas 6y agoBetter in some ways, worse in others. Better than either, I think, is both.
- taywrobel 6y ago“It’s well supported”, yet on latest mobile Safari, it doesn’t appear to work at all. This w3 demo code does not show me the full name anywhere in the rendered content -https://www.w3schools.com/tags/tryit.asp?filename=tryhtml_abbr_test https://www.w3schools.com/tags/tryit.asp?filename=tryhtml_ab...
- ficklepickle 6y agoWhat about a long-press on the abbreviation? Does that do anything? I'm not on mobile now but I vaguely recall that working on some mobile platforms.
- lucasverra 6y agoNoup, just tried
- deleted 6y ago[deleted]
- snazz 6y agoAlthough it works on desktop Safari, there's no way to tell that you should be able to hover over it.
- hashtekar 6y agoChrome on Android rather (un)helpfully selects 'The WHO' and gives me a link to the rock band.
- justusthane 6y agoThat would have nothing to do with the HTML abbr tag. That’s just Google Assistant being Google Assistant.
- hashtekar 6y agoUnderstood. It's a bit like the Google Assistant saying, 'Stand aside, I don't need the instructions. I'm being helpful.' And then doing the wrong thing. It should just RTFM.
- heavyset_go 6y agoDoes <abbr> work well on Android and iOS?
- californical 6y agoNot working for me on iOS
- agent86 6y agoRelevant to the parent here, I prefer to use a link because it is more commonly expected and it gives me the opportunity to refer to a quality source for an in-depth explanation of what I'm referencing. 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.
- rhizome 6y agoThis is how you do that: Conflict-free Replicated Data Types (<a href="...">CRDT</a>) ...then you use "CRDT" for the rest of the document.
- heavenlyblue 6y agoIt doesn’t work on mobile
- mcculley 6y agoDo both!
- dguest 6y agoWow, that's awesome! Thanks for the tip! 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.
- SketchySeaBeast 6y agoDon't even have to - the third paragraph down they set the standard with "Operational Transform (OT)"
- samatman 6y agoI agree, as does every good style guide, and even that can be improved by also making it a link. Hypertext is great, links are practically free, I encourage authors to be liberal in applying them.
- kevinpet 6y agoThat's still lazy writing. Every blog should be written with the assumption it will be encountered by a non-specialist. Expanding abbreviations on first use and offering a brief explanation of jargon is enough to let these readers know if the article is something they are interested in.
- Shared404 6y agoBut also, the blog post should be able to focus on it's own business logic so to speak. The same arguments for and against using libraries apply here, and it's up to the author which works best for their piece.
- Sharlin 6y agoThis is what introductory paragraphs/sections/chapters are for. Someone already well acquainted with the subject matter can quickly skim through them, while others less familiar with it get a quick catch-up.
- Shared404 6y agoI agree. But that's not always the best solution. 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.
- bosswipe 6y agoEvery blog? That's silly. People are allowed to have conversations about niche topics that you are not familiar with. You aren't the audience of every blog.
- danenania 6y agoThat's true, but most people underestimate how opaque their writing can be even to other experts. It doesn't mean you have to explain every piece of jargon, but you can often greatly improve the clarity of your writing, including for expert readers, by targeting at least a few levels of expertise below where you think your audience is. We all have gaps in our knowledge that will seem basic or obvious to others, no matter how expert we are in a topic.
- mlinksva 6y agoWe also have select-contextmenu-search on both desktop and mobile, for any word or acronym. Links are nice for disambiguation or to point to a recommended resource, but they're hardly essential, nor are in-line expansions or definitions.
- jchook 6y agoIn defense, the first sentence links to a Youtube video that expands the acronym in the first 10 seconds. The video also gives good context for the article, even for a beginner to the topic.
- CydeWeys 6y agoSeriously. It needs to be explained the FIRST TIME it appears, and it shouldn't be abbreviated in the title. I read for a minute thinking he was talking about Chrome Remote Desktop (which is what CRDT means to me). Mods, can we expand the acronym in the title of this submission please?
- PaulDavisThe1st 6y agoOr some new-old sort of visual display device ... Cathode Ray Display Terminal :)
- crazygringo 6y agoThat was my first thought. "Wait... is there such a thing as a cathode-ray DIGITAL tube now...?!?!" I mean, if SLR's became DSLR's... I just assume any "D" means we're digital now! :)
- CydeWeys 6y agoIf I didn't use Chrome Remote desktop every day then this definitely would've been my initial assumption as well. Acronym for an obsolete technology but with an added "D"? We've gone digital now, baby!
- serverholic 6y agoIs it really that hard to google? If you're trying to learn about a subject it can get annoying to repeatedly have to jump to the meat of the article or fast forward if you're watching a video.
- root_axis 6y agoObviously googling isn't hard, but having to google what could be easily explained in the text breaks one's concentration, something that is critical for most readers.
- serverholic 6y agoA single quick search and you're good to go. Besides, if you need to look it up then you're probably better off reading a quick summary anyways. 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.
- root_axis 6y agoIf the article is titled "HTTP is the future" yes, I think unpacking the acronym is appropriate. Also, he's not getting "beat up", it's just a mild criticism regarding how the article was written, it's not that big of a deal.
- lotsofpulp 6y agoIs it really that hard to spell it out and then put the abbreviation in parenthesis the first time it is used?
- spicymaki 6y agoGiven that the author defines CRDT (conflict-free replicated data type) a few paragraphs in, it might have been accidental. The author might have re-ordered a few of the paragraphs during editing.
- tachyonbeam 6y agoYou can also be even nicer and have the first expansion of the acronym link to a wikipedia page or other relevant explanation.
- Naac 6y agoWhile I agree that reading the title was confusing ( as I am not familiar with CRDT ), I think the writing style was actually very good. 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.
- theon144 6y agoYup, strong agree. The article did a great job of capturing the "story" of the competing approaches really well, I didn't even mind that the acronym wasn't explained until later.
- IncRnd 6y agoThis is called "burying the lede", where the newsworthy portion is buried somewhere later instead of being mentioned upfront. It's best not to do this, since not all readers will read two thirds of a story in order to determine the subject.
- andrewprock 6y agoI've seen this writing tactic become more and more common over the years. It shows disrespect for your audience, and tends to play well only when "preaching to the choir". 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.
- rpdillon 6y agoI don't think this is a good example of burying the lede. If I wanted to bury the lede on this post, I'd do this: > 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.
- deleted 6y ago[deleted]
- colesantiago 6y agoAgreed, 29 mentions of the acronym 'CRDT' and I had no idea what it was until I had to break my reading flow and google it, it sounded like buzzword soup to me. Engineers, when talking about technical concepts with acronyms, always expand them for the first time to your readers!
- deleted 6y ago[deleted]
- butterisgood 6y agoI’m sure a casual, non-technical reader of Hacker News would be unaware of most of the headlines here. Google is your friend, and CRDTs are part of the language of distributed systems. To some degree, one has to help themselves.
- Quarrelsome 6y agoI was at least happy that the wiki detour introduced me to "gossip protocols" which is probably now one of my all-time favourite technology namings.
- nickflorez 6y agoAmen.
- bosswipe 6y agoHe wasn't writing for you, he was obviously writing for people familiar with these algorithms.
- josephg 6y agoAuthor here. Thanks for the feedback - I’ll update the article. I’m a little embarrassed to admit I didn’t even notice.
- regulation_d 6y agoI'm of the camp that focusing on the acronym stuff is missing the point: that was a thoughtful, well-written piece. I, for one, am grateful that you took the time to write it.
- josephg 6y agoThanks. I expanded the acronym it when it became relevant to the story. But judging by the comments here, lots of folks were distracted and frustrated that they didn't know what the acronym meant earlier. Anyway, I've updated the introductory paragraph to make it more clear.
- doomjunky 6y agoIt's feels like this document is heavy as ten years of work, thanks.
- mcdirty 6y agoI literally closed the article after reading the first blurb, because it wasn't explained. Just started googling.
- KirinDave 6y agoI don't understand why you think that writing on a very technical subject needs to build you a ladder to climb on as a prerequisite. There is a link to a very high quality talk right at the top of the article for folks who wanted to dive deeper that specifically makes that effort. 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.
- rhizome 6y agoThere are practices for informative writing that have been developed over decades and decades that recommend, among other things, defining initialisms on first use.
- KirinDave 6y agoI read hundreds of pages of such writing a week and I can assure you that if this is a practice, it is not well observed by academics or engineers in the field.
- deepsun 6y agoI strongly disagree, that forces author to spend extra time on explaining everything. That's why it's often so hard for me to find quality in-depth advanced blogs on various technologies and fields -- because they all tend to be really introductory. So there's either papers or tutorials, but nothing in-between. E.g. a different-angle explanation of the same thing, or comparison with another tech who came from that. 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.
- losvedir 6y ago> Don't write like this. Respect your readers 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."
- dang 6y agoThe trouble with comments like this is that they make discussions shallower and more generic, which makes for worse threads [1]. Actually it's not so much the comment as the upvotes, but shallow-generic-indignant comments routinely attract upvotes, so alas it amounts to the same thing. 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 https://news.ycombinator.com/newsguidelines.html [1] https://hn.algolia.com/?dateRange=all&page=0&prefix=true&sort=byDate&type=comment&query=generic%20discussion%20by:dang https://hn.algolia.com/?dateRange=all&page=0&prefix=true&sor...