{"action":"created","comment":{"url":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/comments/43877237","id":43877237,"diff_hunk":"@@ -81,57 +81,64 @@ STATIC const mp_doc_t help_table_types[] = {\n     {&microbit_accelerometer_type, \"MicroBitAccelerometer type\\n\"},\n };\n \n+// Consistency between messages and minimal jargon improves help text.\n STATIC const mp_doc_t help_table_instances[] = {\n-    {&microbit_module, \"A toolbox of code to control the micro:bit hardware.\\n\"},\n-    {&microbit_panic_obj, \"panic() -- enter panic mode (requires a restart).\\n\"},\n-    {&microbit_random_obj, \"random(n) -- return a random number between 0 and 'n'-1.\\n\"},\n-    {&microbit_sleep_obj, \"sleep(n) -- wait for 'n' milliseconds (1 second = 1000).\\n\"},\n-    {&microbit_running_time_obj, \"running_time() -- get the number of milliseconds since reset.\\n\"},\n-    {&microbit_accelerometer_obj, \"A toolbox of code to detect the device's position (orientation).\\n\"},\n-    {&microbit_accelerometer_get_x_obj, \"get_x() -- get the device's X axis reading.\\n\"},\n-    {&microbit_accelerometer_get_y_obj, \"get_y() -- get the device's Y axis reading.\\n\"},\n-    {&microbit_accelerometer_get_z_obj, \"get_z() -- get the device's Z axis reading.\\n\"},\n-    {&microbit_button_a_obj, \"Represents button A. Use its is_pressed() method to discover its status.\\n\"},\n-    {&microbit_button_b_obj, \"Represents button B. Use its is_pressed() method to discover its status.\\n\"},\n-    {&microbit_button_is_pressed_obj, \"is_pressed() -- True if the button is pressed, else False.\\n\"},\n-    {&microbit_compass_obj, \"A toolbox of code to detect the device's heading.\\n\"},\n+    {&microbit_module, \"A group of tools to control the micro:bit hardware.\\n\"},\n+    // System state objects\n+    {&microbit_panic_obj, \"Begin panic() mode (requires a reset).\\n\"},\n+    {&microbit_random_obj, \"Return a random(number) between 0 and 'number - 1'.\\n\"},\n+    {&microbit_sleep_obj, \"Wait for sleep(time) 'time' milliseconds (1 second = 1000 ms).\\n\"},\n+    {&microbit_running_time_obj, \"Return running_time() in milliseconds since micro:bit's last reset.\\n\"},\n+    // Accelerometer 3D orientation\n+    {&microbit_accelerometer_obj, \"Detect the microbit's position (3D orientation).\\n\"},\n+    {&microbit_accelerometer_get_x_obj, \"Return micro:bit's X axis position.\\n\"},\n+    {&microbit_accelerometer_get_y_obj, \"Return micro:bit's Y axis position.\\n\"},\n+    {&microbit_accelerometer_get_z_obj, \"Return micro:bit's Z axis position.\\n\"},\n+    // Pushbutton\n+    {&microbit_button_a_obj, \"micro:bit's 'A' button. is_pressed() is True when button is pressed down.\\n\"},\n+    {&microbit_button_b_obj, \"micro:bit's 'B' button. is_pressed() is True when button is pressed down.\\n\"},","path":"source/microbit/help.c","position":32,"original_position":32,"commit_id":"ca341d09842898cd5499aa47cd42bb45a30da166","original_commit_id":"ca341d09842898cd5499aa47cd42bb45a30da166","user":{"login":"ntoll","id":37602,"avatar_url":"https://avatars.githubusercontent.com/u/37602?v=3","gravatar_id":"","url":"https://api.github.com/users/ntoll","html_url":"https://github.com/ntoll","followers_url":"https://api.github.com/users/ntoll/followers","following_url":"https://api.github.com/users/ntoll/following{/other_user}","gists_url":"https://api.github.com/users/ntoll/gists{/gist_id}","starred_url":"https://api.github.com/users/ntoll/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/ntoll/subscriptions","organizations_url":"https://api.github.com/users/ntoll/orgs","repos_url":"https://api.github.com/users/ntoll/repos","events_url":"https://api.github.com/users/ntoll/events{/privacy}","received_events_url":"https://api.github.com/users/ntoll/received_events","type":"User","site_admin":false},"body":"Ahha... my confusion. Ignore the above. :-)","created_at":"2015-11-04T13:00:30Z","updated_at":"2015-11-04T13:00:30Z","html_url":"https://github.com/bbcmicrobit/micropython/pull/65#discussion_r43877237","pull_request_url":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65","_links":{"self":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/comments/43877237"},"html":{"href":"https://github.com/bbcmicrobit/micropython/pull/65#discussion_r43877237"},"pull_request":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65"}}},"pull_request":{"url":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65","id":49619804,"html_url":"https://github.com/bbcmicrobit/micropython/pull/65","diff_url":"https://github.com/bbcmicrobit/micropython/pull/65.diff","patch_url":"https://github.com/bbcmicrobit/micropython/pull/65.patch","issue_url":"https://api.github.com/repos/bbcmicrobit/micropython/issues/65","number":65,"state":"open","locked":false,"title":"[WIP] Add consistency and minimize jargon in help text","user":{"login":"willingc","id":2680980,"avatar_url":"https://avatars.githubusercontent.com/u/2680980?v=3","gravatar_id":"","url":"https://api.github.com/users/willingc","html_url":"https://github.com/willingc","followers_url":"https://api.github.com/users/willingc/followers","following_url":"https://api.github.com/users/willingc/following{/other_user}","gists_url":"https://api.github.com/users/willingc/gists{/gist_id}","starred_url":"https://api.github.com/users/willingc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/willingc/subscriptions","organizations_url":"https://api.github.com/users/willingc/orgs","repos_url":"https://api.github.com/users/willingc/repos","events_url":"https://api.github.com/users/willingc/events{/privacy}","received_events_url":"https://api.github.com/users/willingc/received_events","type":"User","site_admin":false},"body":"Relates to #21.\r\n\r\nThis is a rough draft pass at editing the individual help messages. I'm open to suggestions from others that: 1) would benefit teaching an 11 year old or 2) offer greater precision in user friendly language.\r\n\r\nSome tips on teaching and jargon.\r\nhttp://csteachingtips.org/browse-all?search_api_views_fulltext=help+messages\r\n\r\nWhile common and familiar to adult developers, some of the existing help text is imprecise and is a bit heavy on jargon vs. real world language.","created_at":"2015-11-03T22:11:07Z","updated_at":"2015-11-04T13:00:30Z","closed_at":null,"merged_at":null,"merge_commit_sha":"9b0ec35354d318cf5a5ef678791af289ac65057e","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65/commits","review_comments_url":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65/comments","review_comment_url":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/comments{/number}","comments_url":"https://api.github.com/repos/bbcmicrobit/micropython/issues/65/comments","statuses_url":"https://api.github.com/repos/bbcmicrobit/micropython/statuses/ca341d09842898cd5499aa47cd42bb45a30da166","head":{"label":"willingc:help-jargon","ref":"help-jargon","sha":"ca341d09842898cd5499aa47cd42bb45a30da166","user":{"login":"willingc","id":2680980,"avatar_url":"https://avatars.githubusercontent.com/u/2680980?v=3","gravatar_id":"","url":"https://api.github.com/users/willingc","html_url":"https://github.com/willingc","followers_url":"https://api.github.com/users/willingc/followers","following_url":"https://api.github.com/users/willingc/following{/other_user}","gists_url":"https://api.github.com/users/willingc/gists{/gist_id}","starred_url":"https://api.github.com/users/willingc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/willingc/subscriptions","organizations_url":"https://api.github.com/users/willingc/orgs","repos_url":"https://api.github.com/users/willingc/repos","events_url":"https://api.github.com/users/willingc/events{/privacy}","received_events_url":"https://api.github.com/users/willingc/received_events","type":"User","site_admin":false},"repo":{"id":44709399,"name":"micropython-1","full_name":"willingc/micropython-1","owner":{"login":"willingc","id":2680980,"avatar_url":"https://avatars.githubusercontent.com/u/2680980?v=3","gravatar_id":"","url":"https://api.github.com/users/willingc","html_url":"https://github.com/willingc","followers_url":"https://api.github.com/users/willingc/followers","following_url":"https://api.github.com/users/willingc/following{/other_user}","gists_url":"https://api.github.com/users/willingc/gists{/gist_id}","starred_url":"https://api.github.com/users/willingc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/willingc/subscriptions","organizations_url":"https://api.github.com/users/willingc/orgs","repos_url":"https://api.github.com/users/willingc/repos","events_url":"https://api.github.com/users/willingc/events{/privacy}","received_events_url":"https://api.github.com/users/willingc/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/willingc/micropython-1","description":"Port of MicroPython for the BBC micro:bit","fork":true,"url":"https://api.github.com/repos/willingc/micropython-1","forks_url":"https://api.github.com/repos/willingc/micropython-1/forks","keys_url":"https://api.github.com/repos/willingc/micropython-1/keys{/key_id}","collaborators_url":"https://api.github.com/repos/willingc/micropython-1/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/willingc/micropython-1/teams","hooks_url":"https://api.github.com/repos/willingc/micropython-1/hooks","issue_events_url":"https://api.github.com/repos/willingc/micropython-1/issues/events{/number}","events_url":"https://api.github.com/repos/willingc/micropython-1/events","assignees_url":"https://api.github.com/repos/willingc/micropython-1/assignees{/user}","branches_url":"https://api.github.com/repos/willingc/micropython-1/branches{/branch}","tags_url":"https://api.github.com/repos/willingc/micropython-1/tags","blobs_url":"https://api.github.com/repos/willingc/micropython-1/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/willingc/micropython-1/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/willingc/micropython-1/git/refs{/sha}","trees_url":"https://api.github.com/repos/willingc/micropython-1/git/trees{/sha}","statuses_url":"https://api.github.com/repos/willingc/micropython-1/statuses/{sha}","languages_url":"https://api.github.com/repos/willingc/micropython-1/languages","stargazers_url":"https://api.github.com/repos/willingc/micropython-1/stargazers","contributors_url":"https://api.github.com/repos/willingc/micropython-1/contributors","subscribers_url":"https://api.github.com/repos/willingc/micropython-1/subscribers","subscription_url":"https://api.github.com/repos/willingc/micropython-1/subscription","commits_url":"https://api.github.com/repos/willingc/micropython-1/commits{/sha}","git_commits_url":"https://api.github.com/repos/willingc/micropython-1/git/commits{/sha}","comments_url":"https://api.github.com/repos/willingc/micropython-1/comments{/number}","issue_comment_url":"https://api.github.com/repos/willingc/micropython-1/issues/comments{/number}","contents_url":"https://api.github.com/repos/willingc/micropython-1/contents/{+path}","compare_url":"https://api.github.com/repos/willingc/micropython-1/compare/{base}...{head}","merges_url":"https://api.github.com/repos/willingc/micropython-1/merges","archive_url":"https://api.github.com/repos/willingc/micropython-1/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/willingc/micropython-1/downloads","issues_url":"https://api.github.com/repos/willingc/micropython-1/issues{/number}","pulls_url":"https://api.github.com/repos/willingc/micropython-1/pulls{/number}","milestones_url":"https://api.github.com/repos/willingc/micropython-1/milestones{/number}","notifications_url":"https://api.github.com/repos/willingc/micropython-1/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/willingc/micropython-1/labels{/name}","releases_url":"https://api.github.com/repos/willingc/micropython-1/releases{/id}","created_at":"2015-10-21T23:04:09Z","updated_at":"2015-10-21T23:04:10Z","pushed_at":"2015-11-03T21:58:48Z","git_url":"git://github.com/willingc/micropython-1.git","ssh_url":"git@github.com:willingc/micropython-1.git","clone_url":"https://github.com/willingc/micropython-1.git","svn_url":"https://github.com/willingc/micropython-1","homepage":"","size":795,"stargazers_count":0,"watchers_count":0,"language":"C","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"bbcmicrobit:master","ref":"master","sha":"1ee2b408aea1446482f1acc52a8d2a20503fe900","user":{"login":"bbcmicrobit","id":15104236,"avatar_url":"https://avatars.githubusercontent.com/u/15104236?v=3","gravatar_id":"","url":"https://api.github.com/users/bbcmicrobit","html_url":"https://github.com/bbcmicrobit","followers_url":"https://api.github.com/users/bbcmicrobit/followers","following_url":"https://api.github.com/users/bbcmicrobit/following{/other_user}","gists_url":"https://api.github.com/users/bbcmicrobit/gists{/gist_id}","starred_url":"https://api.github.com/users/bbcmicrobit/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bbcmicrobit/subscriptions","organizations_url":"https://api.github.com/users/bbcmicrobit/orgs","repos_url":"https://api.github.com/users/bbcmicrobit/repos","events_url":"https://api.github.com/users/bbcmicrobit/events{/privacy}","received_events_url":"https://api.github.com/users/bbcmicrobit/received_events","type":"Organization","site_admin":false},"repo":{"id":40358251,"name":"micropython","full_name":"bbcmicrobit/micropython","owner":{"login":"bbcmicrobit","id":15104236,"avatar_url":"https://avatars.githubusercontent.com/u/15104236?v=3","gravatar_id":"","url":"https://api.github.com/users/bbcmicrobit","html_url":"https://github.com/bbcmicrobit","followers_url":"https://api.github.com/users/bbcmicrobit/followers","following_url":"https://api.github.com/users/bbcmicrobit/following{/other_user}","gists_url":"https://api.github.com/users/bbcmicrobit/gists{/gist_id}","starred_url":"https://api.github.com/users/bbcmicrobit/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/bbcmicrobit/subscriptions","organizations_url":"https://api.github.com/users/bbcmicrobit/orgs","repos_url":"https://api.github.com/users/bbcmicrobit/repos","events_url":"https://api.github.com/users/bbcmicrobit/events{/privacy}","received_events_url":"https://api.github.com/users/bbcmicrobit/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/bbcmicrobit/micropython","description":"Port of MicroPython for the BBC micro:bit","fork":false,"url":"https://api.github.com/repos/bbcmicrobit/micropython","forks_url":"https://api.github.com/repos/bbcmicrobit/micropython/forks","keys_url":"https://api.github.com/repos/bbcmicrobit/micropython/keys{/key_id}","collaborators_url":"https://api.github.com/repos/bbcmicrobit/micropython/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/bbcmicrobit/micropython/teams","hooks_url":"https://api.github.com/repos/bbcmicrobit/micropython/hooks","issue_events_url":"https://api.github.com/repos/bbcmicrobit/micropython/issues/events{/number}","events_url":"https://api.github.com/repos/bbcmicrobit/micropython/events","assignees_url":"https://api.github.com/repos/bbcmicrobit/micropython/assignees{/user}","branches_url":"https://api.github.com/repos/bbcmicrobit/micropython/branches{/branch}","tags_url":"https://api.github.com/repos/bbcmicrobit/micropython/tags","blobs_url":"https://api.github.com/repos/bbcmicrobit/micropython/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/bbcmicrobit/micropython/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/bbcmicrobit/micropython/git/refs{/sha}","trees_url":"https://api.github.com/repos/bbcmicrobit/micropython/git/trees{/sha}","statuses_url":"https://api.github.com/repos/bbcmicrobit/micropython/statuses/{sha}","languages_url":"https://api.github.com/repos/bbcmicrobit/micropython/languages","stargazers_url":"https://api.github.com/repos/bbcmicrobit/micropython/stargazers","contributors_url":"https://api.github.com/repos/bbcmicrobit/micropython/contributors","subscribers_url":"https://api.github.com/repos/bbcmicrobit/micropython/subscribers","subscription_url":"https://api.github.com/repos/bbcmicrobit/micropython/subscription","commits_url":"https://api.github.com/repos/bbcmicrobit/micropython/commits{/sha}","git_commits_url":"https://api.github.com/repos/bbcmicrobit/micropython/git/commits{/sha}","comments_url":"https://api.github.com/repos/bbcmicrobit/micropython/comments{/number}","issue_comment_url":"https://api.github.com/repos/bbcmicrobit/micropython/issues/comments{/number}","contents_url":"https://api.github.com/repos/bbcmicrobit/micropython/contents/{+path}","compare_url":"https://api.github.com/repos/bbcmicrobit/micropython/compare/{base}...{head}","merges_url":"https://api.github.com/repos/bbcmicrobit/micropython/merges","archive_url":"https://api.github.com/repos/bbcmicrobit/micropython/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/bbcmicrobit/micropython/downloads","issues_url":"https://api.github.com/repos/bbcmicrobit/micropython/issues{/number}","pulls_url":"https://api.github.com/repos/bbcmicrobit/micropython/pulls{/number}","milestones_url":"https://api.github.com/repos/bbcmicrobit/micropython/milestones{/number}","notifications_url":"https://api.github.com/repos/bbcmicrobit/micropython/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/bbcmicrobit/micropython/labels{/name}","releases_url":"https://api.github.com/repos/bbcmicrobit/micropython/releases{/id}","created_at":"2015-08-07T11:58:53Z","updated_at":"2015-11-03T03:29:02Z","pushed_at":"2015-11-03T22:11:18Z","git_url":"git://github.com/bbcmicrobit/micropython.git","ssh_url":"git@github.com:bbcmicrobit/micropython.git","clone_url":"https://github.com/bbcmicrobit/micropython.git","svn_url":"https://github.com/bbcmicrobit/micropython","homepage":"","size":13169,"stargazers_count":93,"watchers_count":93,"language":"C","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":13,"mirror_url":null,"open_issues_count":18,"forks":13,"open_issues":18,"watchers":93,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65"},"html":{"href":"https://github.com/bbcmicrobit/micropython/pull/65"},"issue":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/issues/65"},"comments":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/issues/65/comments"},"review_comments":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65/comments"},"review_comment":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/pulls/65/commits"},"statuses":{"href":"https://api.github.com/repos/bbcmicrobit/micropython/statuses/ca341d09842898cd5499aa47cd42bb45a30da166"}}}}