For example, when explaining bitcoin to people I use the analogy of a stack of receipts. That's not technically how a blockchain works, but my mom doesn't care how a blockchain works.
If I were explaining them to someone less technical I'd say something like they're a way to package programs with the other stuff programs need to run so that they can be reliably and quickly started up and moved from place to place.
So it makes sense to provide an initial explanation of one in terms of the other, in special for people who already have some mental model of what virtual machines do.
That is... yes, that's technically true but to the end user there is very very little difference, if any, unless you start playing with advanced stuff that affects the guts.
Imagine you have to install a database (let's say postgres) on your machine. You could just install it the regular way - when you do this postgres uses certain things by default like the port 5432.
Now you're going to install a different piece of software on the machine, but this software also uses port 5432 by default and there's an error about the port already being in use. This is a pain, now you have to change the default port. It turns out these conflicts are happening for a lot of things on the machine and it's a hassle to have to make non-standard changes all over the place that you have to keep track of.
For your first attempt to solve this you decide to run postgres in a virtual machine and connect to that, but now you have an entire extra operating system to deal with and all of the overhead that comes with that. Plus you have to configure access to the VM and get all of those pieces to work too.
It'd be nice if there was a way to just install postgres in a place that is easily accessible, but separate from the rest of your machine with regard to things like ports and such. A "container" that it could be installed in that automatically handles things like port conflicts in some magical backend you don't have to deal with so it looks to you like you can always just use the defaults. This container model is basically docker (or at least my current understanding of it).
Which it isn't, and I still don't know how to attach permanent storage to a docker (if thats even the right term).
Outside of trickery requiring the use of bind mounts (I use one to share ~/.ssh between a host user and container user, for example), volumes are recommended.
OH MY GOSH CAN YOU PEOPLE NOT SEE HOW BADLY DEFINED ALL OF THE NOMENCLATURE IS?
Edit: Useful as in "knowing is half the battle". Being able to make an informed choice is worth something, even if it takes extra effort to filter back down.
This doesn't help someone who is completely new to the list topic though. Even worse they're probably going to get bad information.
So many times something is created to solve a particular problem, and for those who have experienced that problem the need for the solution is obvious. But for those of us who come along later it's not so obvious why I would want to use X.
I've thought many times that the number one thing that should be explained in any documentation, article about a technology, etc. is what problems this solves and give examples of the problems and how this is a solution to those problems.
· How to get an open source community to be interested in helping you | https://news.ycombinator.com/item?id=15538112 (2017Oct:140points,45comments)
And a checklist for the reverse, as you discuss:
When I go to a project's site, I should be able to tell what they do and what they're for within 5-10 seconds, preferably without any scrolling (depending on screen size) and definitely without having to click on anything.
(People usually don't link to the README file)
Since then, whenever I make a website (or a README.md) for my open-source projects, I always make sure that it starts with
1. a short description of what the project is/does in one or two sentences, and
2. a longer explanation of the how and why in one or two paragraphs.
Representative example: https://github.com/sapcc/limes/tree/master/README.md