If you saw a library for say Image Processing or cattle husbandry for Java/JVM would you insist that the project provide a description of “Java”? I’m going to guess if you’re being honest you’d say no. CAN really is not an obscure thing at all. Also it is ones of those things that if you don’t know what it is, you probably don’t need this. Otherwise the google burden is minimal for the curious.
Obscure or not, I think the latter part of this comment is the important part. If you don't know what it is, you are not the target audience and you won't become the target audience by suddenly knowing what a CAN bus is.
So no, I'd say it's actually not worth the effort to add an explanation. It may even give real users the wrong idea.
If you don't know what it is, you are not the target audience and you won't become the target audience by suddenly knowing what a CAN bus is.
So you've never visited a web site, read a bit about a topic you knew nothing about, and then thought, "Wow, that sounds like something I'd like to get into?"
There are a lot of people out there who are curious about the world around them and enjoy expanding what they know instead of stagnating in a knowledge silo.
I didn't "insist". I offered a suggestion. In my understanding that's one of the reasons people put up "Show HN" posts. It was intended as entirely constructive, and I still think it is a good suggestion. CAN is obscure enough that I'd never heard of it, and yet it is something that I would have an interest in.
You seem to think I was nitpicking the post (unless I'm reading you wrong), and that was not at all my intention.
> I'm a very technical person, and I honestly don't think I'd ever heard of it.
> CAN is obscure enough that I’d never heard of it.
These types of statements are why I said “insist”.
There is really is almost no way to make statements like these without sounding foolish. You’re asking us to posit some compelling reason that anything you don’t know is “obscure”!
As someone doing quite a bit of technical writing I’m sensitive to this topic because it really is a type of bikeshedding, which is a patently destructive criticism (even if usually unintentional). It might not be bikeshedding if one has some stronger evidence. My evidence is that CAN is in the marketing material for any automotive car scanner from $10 to $10000. It’s literally as ubiquitous as Ethernet in the US and Europe. As someone else mentioned this really doesn’t matter, what matters is if the term is obscure to the intended users/audience.
Tech writing is about economy, and there are thoughtful discussions to be had about what needs to be described, and what is assumed from the audience and providing an ideal user experience. Appeals to ones own experience unless you’re a member of a special audience are usually the worst.
And the exact same thing can be said about “Java” or in this instance “Python” or any other jargon. Why does no one ask for those terms highlighted? All technical documentation is not a Wikipedia article. It’s just not appropriate imo.
I'd posit that the user base of java, python, etc, huge topics in their own right, vastly outnumbers the users of CAN. It should just come down to simple numbers. I'd welcome that linkability too, makes bridging out to new unfamiliar territories go a lot smoother for the uninitiated. Call it improving the discoverability of things.
