{"action":"created","issue":{"url":"https://api.github.com/repos/opencontainers/image-spec/issues/425","repository_url":"https://api.github.com/repos/opencontainers/image-spec","labels_url":"https://api.github.com/repos/opencontainers/image-spec/issues/425/labels{/name}","comments_url":"https://api.github.com/repos/opencontainers/image-spec/issues/425/comments","events_url":"https://api.github.com/repos/opencontainers/image-spec/issues/425/events","html_url":"https://github.com/opencontainers/image-spec/issues/425","id":186025955,"number":425,"title":"Should we move examples near the top of their sections?","user":{"login":"RobDolinMS","id":8301581,"avatar_url":"https://avatars.githubusercontent.com/u/8301581?v=3","gravatar_id":"","url":"https://api.github.com/users/RobDolinMS","html_url":"https://github.com/RobDolinMS","followers_url":"https://api.github.com/users/RobDolinMS/followers","following_url":"https://api.github.com/users/RobDolinMS/following{/other_user}","gists_url":"https://api.github.com/users/RobDolinMS/gists{/gist_id}","starred_url":"https://api.github.com/users/RobDolinMS/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/RobDolinMS/subscriptions","organizations_url":"https://api.github.com/users/RobDolinMS/orgs","repos_url":"https://api.github.com/users/RobDolinMS/repos","events_url":"https://api.github.com/users/RobDolinMS/events{/privacy}","received_events_url":"https://api.github.com/users/RobDolinMS/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":1,"created_at":"2016-10-28T21:26:48Z","updated_at":"2016-10-28T21:36:36Z","closed_at":null,"body":"I sat down with a paper copy of the Image spec over lunch yesterday and one of the things that struck me was that it would be more readable if the examples were at the top and then descriptions of each element followed.\r\n\r\nDo others think this would be useful for understandability / readability?"},"comment":{"url":"https://api.github.com/repos/opencontainers/image-spec/issues/comments/257034900","html_url":"https://github.com/opencontainers/image-spec/issues/425#issuecomment-257034900","issue_url":"https://api.github.com/repos/opencontainers/image-spec/issues/425","id":257034900,"user":{"login":"wking","id":209920,"avatar_url":"https://avatars.githubusercontent.com/u/209920?v=3","gravatar_id":"","url":"https://api.github.com/users/wking","html_url":"https://github.com/wking","followers_url":"https://api.github.com/users/wking/followers","following_url":"https://api.github.com/users/wking/following{/other_user}","gists_url":"https://api.github.com/users/wking/gists{/gist_id}","starred_url":"https://api.github.com/users/wking/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wking/subscriptions","organizations_url":"https://api.github.com/users/wking/orgs","repos_url":"https://api.github.com/users/wking/repos","events_url":"https://api.github.com/users/wking/events{/privacy}","received_events_url":"https://api.github.com/users/wking/received_events","type":"User","site_admin":false},"created_at":"2016-10-28T21:36:36Z","updated_at":"2016-10-28T21:36:36Z","body":"On Fri, Oct 28, 2016 at 02:26:49PM -0700, Rob Dolin (MSFT) wrote:\n> … it would be more readable if the examples were at the top and then\n> descriptions of each element followed.\n\nAre there other examples of specs that lead with informative examples?\nI think it might just be a sign that we need to keep working on\nreadability for the normative parts ;).\n"}}
{"actor":{"display_login":"wking"}}