{"action":"created","issue":{"url":"https://api.github.com/repos/kubernetes/kubernetes/issues/16089","repository_url":"https://api.github.com/repos/kubernetes/kubernetes","labels_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/16089/labels{/name}","comments_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/16089/comments","events_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/16089/events","html_url":"https://github.com/kubernetes/kubernetes/issues/16089","id":112730631,"number":16089,"title":"Overhaul kubectl help","user":{"login":"RichieEscarez","id":11762685,"avatar_url":"https://avatars.githubusercontent.com/u/11762685?v=3","gravatar_id":"","url":"https://api.github.com/users/RichieEscarez","html_url":"https://github.com/RichieEscarez","followers_url":"https://api.github.com/users/RichieEscarez/followers","following_url":"https://api.github.com/users/RichieEscarez/following{/other_user}","gists_url":"https://api.github.com/users/RichieEscarez/gists{/gist_id}","starred_url":"https://api.github.com/users/RichieEscarez/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/RichieEscarez/subscriptions","organizations_url":"https://api.github.com/users/RichieEscarez/orgs","repos_url":"https://api.github.com/users/RichieEscarez/repos","events_url":"https://api.github.com/users/RichieEscarez/events{/privacy}","received_events_url":"https://api.github.com/users/RichieEscarez/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/kubernetes/kubernetes/labels/component/kubectl","name":"component/kubectl","color":"0052cc"},{"url":"https://api.github.com/repos/kubernetes/kubernetes/labels/help-wanted","name":"help-wanted","color":"006b75"},{"url":"https://api.github.com/repos/kubernetes/kubernetes/labels/kind/documentation","name":"kind/documentation","color":"c7def8"},{"url":"https://api.github.com/repos/kubernetes/kubernetes/labels/priority/P1","name":"priority/P1","color":"eb6420"},{"url":"https://api.github.com/repos/kubernetes/kubernetes/labels/team/ux","name":"team/ux","color":"d2b48c"}],"state":"open","locked":false,"assignee":null,"milestone":{"url":"https://api.github.com/repos/kubernetes/kubernetes/milestones/18","html_url":"https://github.com/kubernetes/kubernetes/milestones/v1.3","labels_url":"https://api.github.com/repos/kubernetes/kubernetes/milestones/18/labels","id":1638460,"number":18,"title":"v1.3","description":"https://github.com/kubernetes/kubernetes/wiki/Release-1.3","creator":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"open_issues":184,"closed_issues":32,"state":"open","created_at":"2016-03-11T07:40:20Z","updated_at":"2016-05-01T16:30:12Z","due_on":"2016-06-24T07:00:00Z","closed_at":null},"comments":2,"created_at":"2015-10-22T04:51:15Z","updated_at":"2016-05-01T16:40:33Z","closed_at":null,"body":" The new \"[kubectl overview](https://github.com/kubernetes/kubernetes/blob/master/docs/user-guide/kubectl-overview.md)\" document has been created and contains edits of all the kubectl descriptions (all technically reviewed/accurate).\r\n\r\nWe should push these updated/improved descriptions into the individual commands so that they also show up in the terminal and the topics generated for the commands.\r\n\r\n(1)\r\nIn this file:\r\n[md_docs.go](https://github.com/spf13/cobra/blob/master/md_docs.go) in [cobra](https://github.com/spf13/cobra)\r\nWe should update the section titles to replace:\r\n * the references to \"Options\" and \"Options inherited...\" with the term \"Flags\" and \"Flags inherited...\" so its consistently referred to across the commands (ie. they all refer to \"flags\"):\r\n * \"SEE ALSO\" with something more accurate like \"Related commands\"\r\n\r\n(2+)\r\nIn the files in the https://github.com/kubernetes/kubernetes/tree/master/pkg/kubectl/cmd directory, the corresponding kubectl files should be updated to contain all the revised descriptions that we have put the new \"[kubectl overview](https://github.com/kubernetes/kubernetes/blob/master/docs/user-guide/kubectl-overview.md)\".\r\n\r\n@JanetKuo @bgrant0607 @jlowdermilk "},"comment":{"url":"https://api.github.com/repos/kubernetes/kubernetes/issues/comments/216054356","html_url":"https://github.com/kubernetes/kubernetes/issues/16089#issuecomment-216054356","issue_url":"https://api.github.com/repos/kubernetes/kubernetes/issues/16089","id":216054356,"user":{"login":"bgrant0607","id":7725777,"avatar_url":"https://avatars.githubusercontent.com/u/7725777?v=3","gravatar_id":"","url":"https://api.github.com/users/bgrant0607","html_url":"https://github.com/bgrant0607","followers_url":"https://api.github.com/users/bgrant0607/followers","following_url":"https://api.github.com/users/bgrant0607/following{/other_user}","gists_url":"https://api.github.com/users/bgrant0607/gists{/gist_id}","starred_url":"https://api.github.com/users/bgrant0607/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bgrant0607/subscriptions","organizations_url":"https://api.github.com/users/bgrant0607/orgs","repos_url":"https://api.github.com/users/bgrant0607/repos","events_url":"https://api.github.com/users/bgrant0607/events{/privacy}","received_events_url":"https://api.github.com/users/bgrant0607/received_events","type":"User","site_admin":false},"created_at":"2016-05-01T16:40:32Z","updated_at":"2016-05-01T16:40:32Z","body":"Using this issue as a broader umbrella issue.\r\n\r\nIn general, kubectl --help could use a lot of improvement. \r\n\r\n* Out of date: RC help still refers to a v1beta1 field, which was removed almost a year ago.\r\n* Best practices: Most help shows json rather than yaml. \r\n* Consistency: The commands shown are inconsistent across commands.\r\n* Relevant: Help doesn't necessarily reflect the most common scenarios. \r\n* Navigation: Help doesn't suggest alternative or more appropriate commands. Help doesn't direct users to the right resource types. No/few links to online documentation.\r\n* Search: Synopses sometimes don't contain critical words that would help users find the right option. \r\n* Complete usage: Help doesn't indicate which resource types are valid for each command. Resource lists that do exist are hardcoded and not complete.\r\n* Organization: Flags, commands, and resource types are presented in insufficiently organized flat lists.\r\n\r\nSee also #7496, #15741, #19736, #23402\r\n\r\nAlso see the brainstorming doc:\r\nhttps://docs.google.com/document/d/1tPrTL5Fi8BjlIK_XwNz-W260ll2ZYflrdbtnwE1PQoE/edit#\r\n\r\ncc @kubernetes/kubectl "}}