4 ms·

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.
    - colemickens 10y ago
      I see. That page is kind of rough. Doesn't even seem to link to the yaml file, just implicitly references the docs path as if the user has a local enlistment of the kubernetes code. Probably should be a kubectl apply link that directly references the yaml blob url on github. I think any and all help is welcome on the docs, it seems to be a well-known weak spot.
- btym 10y ago
  I often end up referring to the GoDoc and core code when the documentation is lacking. I wish the docs gave a deeper explanation of each component and the object model. There are also places where the content is too specific and not generally applicable. For example, this addon example that assumes you're using the kube-up convenience script: http://kubernetes.io/docs/getting-started-guides/logging-elasticsearch/ http://kubernetes.io/docs/getting-started-guides/logging-ela... No explanation of what the magic flag actually does, just "set this and run kube-up". (the real explanation is "copy the appropriate specs to your cluster addon directory")
  - kozikow 10y ago
    Yeah I generally look at go objects for docs. Also I think just writing configs in go rather than yaml is better. I wrote a post about it: https://kozikow.com/2016/09/02/using-go-to-autogenerate-kubernetes-configs/ https://kozikow.com/2016/09/02/using-go-to-autogenerate-kube... .
    - swozey 10y ago
      Thats for the post. I've been using k8s forever but I'm pretty new to go. It's probably a great idea to start doing things in go instead.
- deleted 10y ago
  [deleted]

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.
  - colemickens 10y ago
    I see. That page is kind of rough. Doesn't even seem to link to the yaml file, just implicitly references the docs path as if the user has a local enlistment of the kubernetes code. Probably should be a kubectl apply link that directly references the yaml blob url on github. I think any and all help is welcome on the docs, it seems to be a well-known weak spot.
btym 10y ago
I often end up referring to the GoDoc and core code when the documentation is lacking. I wish the docs gave a deeper explanation of each component and the object model. There are also places where the content is too specific and not generally applicable. For example, this addon example that assumes you're using the kube-up convenience script: http://kubernetes.io/docs/getting-started-guides/logging-elasticsearch/ http://kubernetes.io/docs/getting-started-guides/logging-ela... No explanation of what the magic flag actually does, just "set this and run kube-up". (the real explanation is "copy the appropriate specs to your cluster addon directory")
- kozikow 10y ago
  Yeah I generally look at go objects for docs. Also I think just writing configs in go rather than yaml is better. I wrote a post about it: https://kozikow.com/2016/09/02/using-go-to-autogenerate-kubernetes-configs/ https://kozikow.com/2016/09/02/using-go-to-autogenerate-kube... .
  - swozey 10y ago
    Thats for the post. I've been using k8s forever but I'm pretty new to go. It's probably a great idea to start doing things in go instead.
deleted 10y ago
[deleted]