> Out of curiosity how do you feel about the current README on Docker's repo?
https://github.com/docker/docker/blob/master/README.mdFrom the perspective of this longtime software developer, this isn't that great either. I'll try to give some specifics.
* The terms "container" and "containerization" seem to mean a lot to the author of the document, but they're never defined well and they're used an awful lot despite this. That kind of thing isn't half-bad marketspeak if the point is to get people thinking about this in the vague "It's the future!" manner that The Fine Article is satirizing (and/or accurately reporting as part of the social dynamics of the industry). The invocation of an unfamiliar term over and over can serve as a form of social proof and generates curiosity. But it might well be what's triggering suspicion on the part of some engineers.
* Positioning containers as an alternative to VMs is somewhat helpful in giving at least some idea of what kind of rough problem space we're working in -- someone familiar with a VM knows that they're often used to reproduce the specific runtime environment a given application needs. But by the end of the section I still have no real idea how "containers" are different other than that they're "lighter." Except for one clue: I know what FreeBSD jails are. So I might guess that something like them is involved -- but you're describing them as "primitives", so there's something else involved and I don't see an explanation of what it is. Is Docker a glorified chroot jail? If it's something more, what's the additional value?
* And... two sections down "escape dependency hell" -- that might be the additional value prop! But again, this section is really confusing. Dependency management means package management, right? But it's being done with Yet Another New Undefined Entity called "Layers" without replacing any other package manager so... we have two package managers? Or Layers aren't package management? What the hell are they? I could guess they're something like an image but I have no idea.
* "Plays well with others" Gives strong hints this is mostly a Unix thing (which, if this is some kind of enhanced chroot jail makes sense). Somewhat in conflict with the hints of platform agnosticism earlier in the document. Is there a story here for Windows, either as a host or for windows apps?
* "Real World Examples" These tell me how to "Dockerize" different server apps... but there's no context about why I might want to do this. What problem am I trying to solve?
And that's the thing -- at the end of this, I don't know what problem I might be trying to solve with Docker. I might guess Docker helps me deploy an application along with a specific normalized runtime environment, but that's from a lot of guessing and reading between the lines rather than from an upfront communication from the text itself.
If my description is accurate, a clearer version of it should be your first sentence. Followed by a second paragraph telling me enough about some specific frictions you've done away with compared to other solutions that I'm wanting to learn more. Then tell me some specific stories about situations where someone might have a problem that Docker is a good fit for, and explain the rough usage that be applied to address it.