{"action":"created","issue":{"url":"https://api.github.com/repos/hypothesis/client/issues/330","repository_url":"https://api.github.com/repos/hypothesis/client","labels_url":"https://api.github.com/repos/hypothesis/client/issues/330/labels{/name}","comments_url":"https://api.github.com/repos/hypothesis/client/issues/330/comments","events_url":"https://api.github.com/repos/hypothesis/client/issues/330/events","html_url":"https://github.com/hypothesis/client/pull/330","id":218454554,"number":330,"title":"Add docs explaining how to test the client on a real mobile device","user":{"login":"robertknight","id":2458,"avatar_url":"https://avatars2.githubusercontent.com/u/2458?v=3","gravatar_id":"","url":"https://api.github.com/users/robertknight","html_url":"https://github.com/robertknight","followers_url":"https://api.github.com/users/robertknight/followers","following_url":"https://api.github.com/users/robertknight/following{/other_user}","gists_url":"https://api.github.com/users/robertknight/gists{/gist_id}","starred_url":"https://api.github.com/users/robertknight/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/robertknight/subscriptions","organizations_url":"https://api.github.com/users/robertknight/orgs","repos_url":"https://api.github.com/users/robertknight/repos","events_url":"https://api.github.com/users/robertknight/events{/privacy}","received_events_url":"https://api.github.com/users/robertknight/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":{"login":"seanh","id":22498,"avatar_url":"https://avatars0.githubusercontent.com/u/22498?v=3","gravatar_id":"","url":"https://api.github.com/users/seanh","html_url":"https://github.com/seanh","followers_url":"https://api.github.com/users/seanh/followers","following_url":"https://api.github.com/users/seanh/following{/other_user}","gists_url":"https://api.github.com/users/seanh/gists{/gist_id}","starred_url":"https://api.github.com/users/seanh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/seanh/subscriptions","organizations_url":"https://api.github.com/users/seanh/orgs","repos_url":"https://api.github.com/users/seanh/repos","events_url":"https://api.github.com/users/seanh/events{/privacy}","received_events_url":"https://api.github.com/users/seanh/received_events","type":"User","site_admin":false},"assignees":[{"login":"seanh","id":22498,"avatar_url":"https://avatars0.githubusercontent.com/u/22498?v=3","gravatar_id":"","url":"https://api.github.com/users/seanh","html_url":"https://github.com/seanh","followers_url":"https://api.github.com/users/seanh/followers","following_url":"https://api.github.com/users/seanh/following{/other_user}","gists_url":"https://api.github.com/users/seanh/gists{/gist_id}","starred_url":"https://api.github.com/users/seanh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/seanh/subscriptions","organizations_url":"https://api.github.com/users/seanh/orgs","repos_url":"https://api.github.com/users/seanh/repos","events_url":"https://api.github.com/users/seanh/events{/privacy}","received_events_url":"https://api.github.com/users/seanh/received_events","type":"User","site_admin":false}],"milestone":null,"comments":2,"created_at":"2017-03-31T09:56:57Z","updated_at":"2017-04-03T12:24:38Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/hypothesis/client/pulls/330","html_url":"https://github.com/hypothesis/client/pull/330","diff_url":"https://github.com/hypothesis/client/pull/330.diff","patch_url":"https://github.com/hypothesis/client/pull/330.patch"},"body":"While testing #327, #328 and #329 I noticed that we do not have documentation explaining the steps required to test the client on an actual device, which are a little different than testing an ordinary web page.\r\n\r\nThis PR explains the steps required to test using a device on the same network as the dev system by configuring the client/service to use URLs that reference the host name of the dev system rather than `localhost`. There are possibly other ways for specific device/OS combinations, but this approach is generic."},"comment":{"url":"https://api.github.com/repos/hypothesis/client/issues/comments/291127623","html_url":"https://github.com/hypothesis/client/pull/330#issuecomment-291127623","issue_url":"https://api.github.com/repos/hypothesis/client/issues/330","id":291127623,"user":{"login":"seanh","id":22498,"avatar_url":"https://avatars0.githubusercontent.com/u/22498?v=3","gravatar_id":"","url":"https://api.github.com/users/seanh","html_url":"https://github.com/seanh","followers_url":"https://api.github.com/users/seanh/followers","following_url":"https://api.github.com/users/seanh/following{/other_user}","gists_url":"https://api.github.com/users/seanh/gists{/gist_id}","starred_url":"https://api.github.com/users/seanh/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/seanh/subscriptions","organizations_url":"https://api.github.com/users/seanh/orgs","repos_url":"https://api.github.com/users/seanh/repos","events_url":"https://api.github.com/users/seanh/events{/privacy}","received_events_url":"https://api.github.com/users/seanh/received_events","type":"User","site_admin":false},"created_at":"2017-04-03T12:24:37Z","updated_at":"2017-04-03T12:24:37Z","body":"I have to say I think it's up to us to determine whether or not our docs are clear rather than waiting for user feedback. Users for the most part aren't going to give us feedback on our docs, and for these docs in particular the intended user audience is us (and also I reviewed these docs by following them from scratch and seeing what confused me). If we do get some user feedback we should consider it of course.\r\n\r\nThat said, I think you're absolutely right that treating hostname as a docs placeholder is a much better approach here that results in clearer and simpler docs. I didn't think of it, I just jumped straight to \"this looks like an env var, so we should make it one\".\r\n\r\nI'm off to bed now so I'll approve this and let you decide, but I think I'd still like to see `$HOSTNAME` written as `<HOSTNAME>` (or whatever style you prefer for docs placeholders) so that it doesn't look like an env var. There are no other env vars on this page though (at least, not any referenced using `$ENVVAR`) so the confusion isn't too bad. But I think it'd be great to have a specific typographic style for docs placeholders and encourage their use liberally throughout the docs. I'll leave it up to you."}}
{"actor":{"display_login":"seanh"}}