4 ms·

Ask HN: Why has Docker so bad documentation?

2 points by sz4kerto 11y ago

I'm trying to use Docker, for things that are slightly more advanced than running bash on the latest Ubuntu image. More specifically, creating a multi-host overlay network. They tell you on the site that Docker supports overlay networking, but on top of that, you can also use Docker Swarm. After that, they give you an example of how to create a swarm, but no examples of a simple overlay network. They claim it (overlay networking) is now production-quality, but then all the docs say is: (TODO: talk about Swarm and the overlay driver) My experience was similar with other topics as well, and it's a bit annoying because I fully believe that containers are going to transform deployment completely...

brudgers 11y ago
Creating a multi-host overlay network sounds like a task with a lot of knowledge dependencies. In a moderately sized organization, there is a better chance that a sizable fraction of that knowledge is institutional knowledge. For a single developer, the odds of the pre-requisite knowledge existing quickly decreases as the size of the knowledge dependency chain grows. There are tools technologies and tutorials designed for a team of size one. Those that aren't will probably require a team of size one to invest significant time working their way up and down the knowledge dependency chain. To put it another way, if containers are going to change the world, then learning them is a long term project. Good luck.
kordless 11y ago
Documentation is hard because you have to have empathy for the user while holding most of the product's capabilities in your head while you write it. Transfer of knowledge has always been difficult, and when you start changing the rules in the middle of trying to explain how it works, you'll end up with a very large challenge. I would assume they'll eventually figure it out and improve it. Until then, the best thing to do is dig, dig, dig.

4 ms·

Ask HN: Why has Docker so bad documentation?

2 points by sz4kerto 11y ago

brudgers 11y ago
Creating a multi-host overlay network sounds like a task with a lot of knowledge dependencies. In a moderately sized organization, there is a better chance that a sizable fraction of that knowledge is institutional knowledge. For a single developer, the odds of the pre-requisite knowledge existing quickly decreases as the size of the knowledge dependency chain grows. There are tools technologies and tutorials designed for a team of size one. Those that aren't will probably require a team of size one to invest significant time working their way up and down the knowledge dependency chain. To put it another way, if containers are going to change the world, then learning them is a long term project. Good luck.
kordless 11y ago
Documentation is hard because you have to have empathy for the user while holding most of the product's capabilities in your head while you write it. Transfer of knowledge has always been difficult, and when you start changing the rules in the middle of trying to explain how it works, you'll end up with a very large challenge. I would assume they'll eventually figure it out and improve it. Until then, the best thing to do is dig, dig, dig.