{"action":"created","issue":{"url":"https://api.github.com/repos/ga4gh/schemas/issues/256","labels_url":"https://api.github.com/repos/ga4gh/schemas/issues/256/labels{/name}","comments_url":"https://api.github.com/repos/ga4gh/schemas/issues/256/comments","events_url":"https://api.github.com/repos/ga4gh/schemas/issues/256/events","html_url":"https://github.com/ga4gh/schemas/issues/256","id":60888002,"number":256,"title":"Human-readable documentation / explicit use cases missing","user":{"login":"nouyang-curoverse","id":8737224,"avatar_url":"https://avatars.githubusercontent.com/u/8737224?v=3","gravatar_id":"","url":"https://api.github.com/users/nouyang-curoverse","html_url":"https://github.com/nouyang-curoverse","followers_url":"https://api.github.com/users/nouyang-curoverse/followers","following_url":"https://api.github.com/users/nouyang-curoverse/following{/other_user}","gists_url":"https://api.github.com/users/nouyang-curoverse/gists{/gist_id}","starred_url":"https://api.github.com/users/nouyang-curoverse/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/nouyang-curoverse/subscriptions","organizations_url":"https://api.github.com/users/nouyang-curoverse/orgs","repos_url":"https://api.github.com/users/nouyang-curoverse/repos","events_url":"https://api.github.com/users/nouyang-curoverse/events{/privacy}","received_events_url":"https://api.github.com/users/nouyang-curoverse/received_events","type":"User","site_admin":false},"labels":[{"url":"https://api.github.com/repos/ga4gh/schemas/labels/Documentation","name":"Documentation","color":"006b75"}],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":33,"created_at":"2015-03-12T19:47:28Z","updated_at":"2015-07-16T12:18:24Z","closed_at":null,"body":"The mass of auto-generated API doc, http://ga4gh.org/documentation/api/v0.5.1/ga4gh_api.html#/, while infinitely better than nothing, is now hindering distilling / reaching clarity and consensus about some simple issues and edge cases (in my opinion). \r\n\r\nCan we move to include more human-readable documentation along with the Avro schemas, or at least in our Github Issues discussions?\r\n\r\nI think this will resolve a lot of confusion being generated because people are submitting solutions/pull-requests that resolve specific use cases. Without making the use cases we have in mind explicit to each other, the fact that our solutions are conflicting and need a step back to resolve may not be readily apparent.\r\n\r\nAdditionally, explicit use cases will easily allow us to write end-user oriented documentation in the future (where here the end-users are actually developers for various institutions / software packages)."},"comment":{"url":"https://api.github.com/repos/ga4gh/schemas/issues/comments/121941718","html_url":"https://github.com/ga4gh/schemas/issues/256#issuecomment-121941718","issue_url":"https://api.github.com/repos/ga4gh/schemas/issues/256","id":121941718,"user":{"login":"maximilianh","id":310861,"avatar_url":"https://avatars.githubusercontent.com/u/310861?v=3","gravatar_id":"","url":"https://api.github.com/users/maximilianh","html_url":"https://github.com/maximilianh","followers_url":"https://api.github.com/users/maximilianh/followers","following_url":"https://api.github.com/users/maximilianh/following{/other_user}","gists_url":"https://api.github.com/users/maximilianh/gists{/gist_id}","starred_url":"https://api.github.com/users/maximilianh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/maximilianh/subscriptions","organizations_url":"https://api.github.com/users/maximilianh/orgs","repos_url":"https://api.github.com/users/maximilianh/repos","events_url":"https://api.github.com/users/maximilianh/events{/privacy}","received_events_url":"https://api.github.com/users/maximilianh/received_events","type":"User","site_admin":false},"created_at":"2015-07-16T12:18:24Z","updated_at":"2015-07-16T12:18:24Z","body":"@benhutton: my assumption was that people have usually apache running\nanyways and have their variants as .VCF files somewhere. In this case, all\nthey have to do is to extract the archive and import their VCF files.\n\nOn Thu, Jul 16, 2015 at 1:59 PM, Ben Hutton <notifications@github.com>\nwrote:\n\n> @diekhans <https://github.com/diekhans> OK, thankyou. That makes sense.\n>\n> @maximilianh <https://github.com/maximilianh> A bit, but I guess I'm\n> coming from the false assumption that people will be writing APIs into\n> existing systems as opposed to creating standalone systems. We (Decipher)\n> would want to make it part of our existing code base, not run a new\n> process. It is still useful to be able to view an implementation though, so\n> thanks for the link! =]\n>\n> —\n> Reply to this email directly or view it on GitHub\n> <https://github.com/ga4gh/schemas/issues/256#issuecomment-121938389>.\n>\n"}}