4 ms·

I feel that the homepage at kubernetes.io is a poor introduction to the project. All the keywords and short descriptions don't add up to a complete picture of

I feel that the homepage at kubernetes.io is a poor introduction to the project. All the keywords and short descriptions don't add up to a complete picture of what Kubernetes does and why someone would want to use it. The opening tagline "Kubernetes is an open-source system for..." seems like a complete description of the project, but to a _newcomer_, the sentence is not easy to parse. The "What is Kubernetes?" page [1] gives a very clear overview of Kubernetes that will make sense both to people who already know about containers in general and those who are new to the concept. Can someone help me understand what type of person the homepage is targeted at? It just doesn't do anything for me. I'm mainly interested because I find that a lot of projects have very poor home pages, even if the rest of the project is awesome. [1] http://kubernetes.io/docs/whatisk8s/ http://kubernetes.io/docs/whatisk8s/

swozey 10y ago
I think that it targets people who already know or have an idea as to what Kubernetes is and are looking to compare/contrast various Docker/rkt schedulers for their infrastructure. I really doubt that they're targeting anyone who isn't familiar with the above and with as in flux and complex as kubernetes is right now (especially regarding documentation/the site) they probably shouldn't albeit deployment and management simplification seems to be a very important goal in the end. The kube docs/pages are mostly just from the github repo. I doubt they've had much editorialization unfortunately.
- TheIronYuppie 10y ago
  I think this is excellent feedback - we should revamp! Disclosure: I work at Google on Kubernetes
  - swozey 10y ago
    One of my huge headaches in working with Kubernetes daily over the last year is how the documentation is dispersed. The documentation on the site will point you to manfiests in github.com/kubernetes/ which just point you back to the documentation on www.kubernetes.io. If you don't know that https://github.com/kubernetes/kubernetes.github.io/tree/master/docs https://github.com/kubernetes/kubernetes.github.io/tree/mast... exists you're in for a bad time.
    - TheIronYuppie 10y ago
      Yes - we've made huge progress against the many many repos of docs, but we're not close to done yet :( Please file bugs! Disclosure: I work at Google on Kubernetes
    - colemickens 10y ago
      I'm confused, those are the docs that are renedered and visible on kubernetes.io.
      - swozey 10y ago
        The docs in github/kubernetes/kubernetes.github.io are what is rendered. The documentation was broken apart at some point. 90% of the time (if not always) when I'm looking for a file mentioned in the actual website docs the link (if one exists) is to the kubernetes repo, not the kubernetes.io repo. Going to the location in the kubernetes repo just gives you a loop back to the website you were just viewing. If you've used k8s docs for any significant amount of time I can pretty much guarantee that you've encountered this. Here's an example; limit-example.yml which is mentioned over and over in the limitrange docs but the file is nowhere to be found; http://kubernetes.io/docs/admin/limitrange/ http://kubernetes.io/docs/admin/limitrange/ If you don't know about the kubernetes.io repo (which someone who has never gone through looking for missing docs will not know about) you'll think to look in the kubernetes repo on github for the missing file, where you think it will be; https://github.com/kubernetes/kubernetes/tree/master/docs/admin/limitrange https://github.com/kubernetes/kubernetes/tree/master/docs/ad... Where it is; https://github.com/kubernetes/kubernetes.github.io/tree/master/docs/admin/limitrange https://github.com/kubernetes/kubernetes.github.io/tree/mast... Edit: I have been poor on submitting doc bug requests because I don't really know what the state of the docs are. If they just migrated, if they're working on cleaning up things, or what. I suppose I'll just start creating issues regarding them in the future. edit: I just realized that's limit.yml, I'm not even sure where limit-example.yml is or if there's any difference. Like the go guys mentioned above, there are also a huge number of undocumented (on k8s.io) features that you'd only find by reading the go-defs.
        10y ago
btmiller 10y ago
Absolutely – as someone looking to enter the container orchestration space, I have been spending time evaluating Docker Swarm (1.12) and Kubernetes. While consensus seems to be that Swarm is immature and "productionability" is questionable, Docker's documentation, while by no means perfect, was by far more approachable than whatever Kubernetes has thrown together. Perhaps that comes as consequence of Docker shooting for the all-built-in approach, but I'd like to see a better overview and ramp-up in the Kubernetes space – their "101" and "201" docs are laughable.
- lewq 10y ago
  We are trying to improve the documentation and developer experience. Please try the new kubeadm install docs and let me know what you think. http://kubernetes.io/docs/getting-started-guides/kubeadm/ http://kubernetes.io/docs/getting-started-guides/kubeadm/ Disclosure: I wrote the doc (but don't work at Google) :)

swozey 10y ago

I think that it targets people who already know or have an idea as to what Kubernetes is and are looking to compare/contrast various Docker/rkt schedulers for their infrastructure. I really doubt that they're targeting anyone who isn't familiar with the above and with as in flux and complex as kubernetes is right now (especially regarding documentation/the site) they probably shouldn't albeit deployment and management simplification seems to be a very important goal in the end. The kube docs/pages are mostly just from the github repo. I doubt they've had much editorialization unfortunately.

TheIronYuppie 10y ago
I think this is excellent feedback - we should revamp! Disclosure: I work at Google on Kubernetes
- swozey 10y ago
  One of my huge headaches in working with Kubernetes daily over the last year is how the documentation is dispersed. The documentation on the site will point you to manfiests in github.com/kubernetes/ which just point you back to the documentation on www.kubernetes.io. If you don't know that https://github.com/kubernetes/kubernetes.github.io/tree/master/docs https://github.com/kubernetes/kubernetes.github.io/tree/mast... exists you're in for a bad time.
  - TheIronYuppie 10y ago
    Yes - we've made huge progress against the many many repos of docs, but we're not close to done yet :( Please file bugs! Disclosure: I work at Google on Kubernetes
  - colemickens 10y ago
    I'm confused, those are the docs that are renedered and visible on kubernetes.io.
    - swozey 10y ago
      The docs in github/kubernetes/kubernetes.github.io are what is rendered. The documentation was broken apart at some point. 90% of the time (if not always) when I'm looking for a file mentioned in the actual website docs the link (if one exists) is to the kubernetes repo, not the kubernetes.io repo. Going to the location in the kubernetes repo just gives you a loop back to the website you were just viewing. If you've used k8s docs for any significant amount of time I can pretty much guarantee that you've encountered this. Here's an example; limit-example.yml which is mentioned over and over in the limitrange docs but the file is nowhere to be found; http://kubernetes.io/docs/admin/limitrange/ http://kubernetes.io/docs/admin/limitrange/ If you don't know about the kubernetes.io repo (which someone who has never gone through looking for missing docs will not know about) you'll think to look in the kubernetes repo on github for the missing file, where you think it will be; https://github.com/kubernetes/kubernetes/tree/master/docs/admin/limitrange https://github.com/kubernetes/kubernetes/tree/master/docs/ad... Where it is; https://github.com/kubernetes/kubernetes.github.io/tree/master/docs/admin/limitrange https://github.com/kubernetes/kubernetes.github.io/tree/mast... Edit: I have been poor on submitting doc bug requests because I don't really know what the state of the docs are. If they just migrated, if they're working on cleaning up things, or what. I suppose I'll just start creating issues regarding them in the future. edit: I just realized that's limit.yml, I'm not even sure where limit-example.yml is or if there's any difference. Like the go guys mentioned above, there are also a huge number of undocumented (on k8s.io) features that you'd only find by reading the go-defs.
      - 10y ago

btmiller 10y ago

Absolutely – as someone looking to enter the container orchestration space, I have been spending time evaluating Docker Swarm (1.12) and Kubernetes. While consensus seems to be that Swarm is immature and "productionability" is questionable, Docker's documentation, while by no means perfect, was by far more approachable than whatever Kubernetes has thrown together. Perhaps that comes as consequence of Docker shooting for the all-built-in approach, but I'd like to see a better overview and ramp-up in the Kubernetes space – their "101" and "201" docs are laughable.

lewq 10y ago
We are trying to improve the documentation and developer experience. Please try the new kubeadm install docs and let me know what you think. http://kubernetes.io/docs/getting-started-guides/kubeadm/ http://kubernetes.io/docs/getting-started-guides/kubeadm/ Disclosure: I wrote the doc (but don't work at Google) :)