Hacker News Reader

Comment by majewsky | Hacker News Reader

This applies to websites of open source projects, too. I remember when I visited docker.com for the first time because someone told me it's the latest shit and I just wanted to know what it is about. I browsed their website for 10 minutes, and summarized the experience to a coworker like this: "As far as I can see, it's the best thing ever and I'd be stupid not to use it, but I still does not know what it actually does."

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

View on HN

Favorite conference quote ever: "So other than unicorns barfing rainbows, what is Docker?"

Thank you. I'm a hardware guy and I've heard about a dozen of explanations of what Docker is and even tried to set it up on my NAS but I still have no idea. And to the person about to comment with your version, I don't really care to know.

Docker is building, running, and sharing VMs from the command line.

Containers are not VMs (virtual machines): https://blog.docker.com/2016/03/containers-are-not-vms/

Thank you for illustrating my point.

I don't understand why people don't frame the explanation in the context of what problem the thing is trying to solve.

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).

Huh? What's a port? How do I "install a database"? I already have Excel on my laptop anyway. You lost me at around the third sentence.

You may not be the target audience. Docker is a tool primarily used to help efficiently deploy your networked applications on new servers. If you don't need to deploy server apps, you can stop reading here. If you do need to deploy apps to servers, docker is worth investigating. It replaces a complex install script and git clones with an efficient clone of a lightweight 'vm' which is ready to run your app immediately.

I hope this PostgreSQL example is simply meant to illustrate a point, and not taken from personal experience. I say that because PostgreSQL is designed to run multiple instances on different ports, and you can run multiple versions along side each other as well. All it takes is editing a couple configuration files.

For me this falls down because my next questions is "cool, so I can run a database in a docker. So my data is save inside the docker?"

Which it isn't, and I still don't know how to attach permanent storage to a docker (if thats even the right term).

What you want is called a "volume". When running a docker container you just pass in the -v option and it maps a directory outside the container to a path that can be used from inside the docker container, e.g. `docker run -v /host/directory:/container/directory ...` would make the directory /host/directory on the host machine accessible inside the container at the path /container/directory.

https://docs.docker.com/engine/admin/volumes/volumes/

While you can directly map the host filesystem to the container filesystem in the manner you describe, that's referred to as a bind mount, not a volume. Volumes reside in the host filesystem as well but are solely managed by Docker.

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.

I'm laughing my head off at how your comment, precisely about this point, has spawned a conversation that has included, "it's like a VM", "it's not like a VM", "it depends on how you define VM", "there are lots of definitions for VM", "you can use a volume, just use the --volume flag", "that's not for volumes, that for bind mounts".

OH MY GOSH CAN YOU PEOPLE NOT SEE HOW BADLY DEFINED ALL OF THE NOMENCLATURE IS?

But they serve the same purpose, even if their implementations are entirely different.

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.

No, they don't serve the same purpose. Try running a Microsoft Exchange in a Docker container on a Linux server. Then try running it in a Windows VM on a Linux server.

Even if they don't always serve the same purpose, they serve a similar purpose in a number of examples. It's still a valid analogy to get someone thinking about how they might work.

Containers are not VMs in the same way that WINE is Not An Emulator.

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.

Pedantry like this is what scared OP away to begin with. Sometimes you have to resist the urge to correct or convey technical details for someone who will not understand the technical details anyway.

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.

I tend to agree in general but I'm not sure in this case. The fact that containers are/were a form of operating system virtualization--which is how they were once referred to--is probably one of the least interesting aspects of how they're used today.

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.

Yeah they are. There are many types of VM.

You’re describing Vagrant

Even more informative could be mentioning what problem it is intended to solve.

Thank you. No one ever describes why anything was written in the first place. And they almost never go out of their way to list the pros/cons of their system. Although I've never even used it, I loved that the BoltDB project mentions other key/value DBs and why you'd pick one over the other, right there in the readme.

Any mention of alternatives is anathema to open source READMEs. This is why the "awesome list of " directories wind up being so useful.

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.

Maybe I'm just unlucky but the vast majority of all 'awesome lists' that I've seen are just massive dumps of links, of extremely varying quality (I mean the links themselves), which isn't that helpful.

You're not unlucky, but there are some gems out there. For someone like you who is experienced in the area and can tell garbage from good stuff, it's worth digging around to find the gems.

This doesn't help someone who is completely new to the list topic though. Even worse they're probably going to get bad information.

Maybe an Awesome list of Awesome lists could help

I'm pretty sure there is one already.

That's also a thing that I try to do for my own projects. For example, the frontpage of http://holocm.org has two lists that are literally titled "This is not for you if..." and "This might be for you if..."

A million times yes!

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.

A discussion on "how a contributor can get the attention of a maintainer" touched on this briefly two weeks ago:

· 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:

· https://twitter.com/sehurlburt/status/921921604140937216

Hell, most of the OS projects that get posted here have that very same problem.

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.

Yes, and in light of this, I still think it's pretty strange that in a project page in GitHub I have to scroll down first before I can read a description.

(People usually don't link to the README file)

so...what _is_ leonardo...

If you refer to SAP Leonardo, I have no fucking clue.

Reply on news.ycombinator.com