clarify GitHub ext svc docs, standardize on terms (#2952)

- fix #2946 by implying that no "repo" scope is needed in the example JSON and explicitly mentioning it in the JSON Schema docs (the explicit mention is omitted from the example JSON for brevity, so that the "token" property is above the fold on an average-sized screen)
- use "repository" not "repo" per https://docs.sourcegraph.com/dev/style_guide

Author: sqs

schema/github.schema.json

@@ -25,7 +25,7 @@
       "default": "http"
     },
     "token": {
-      "description": "A GitHub personal access token with repo and org scope.",
+      "description": "A GitHub personal access token. Create one for GitHub.com at https://github.com/settings/tokens/new?scopes=repo&description=Sourcegraph (for GitHub Enterprise, replace github.com with your instance's hostname). The \"repo\" scope is required to mirror private repositories. If using only public repositories, you can create the token with no scopes.",
       "type": "string",
       "minLength": 1
     },
@@ -40,7 +40,7 @@
       "items": { "type": "string", "pattern": "^[\\w-]+/[\\w.-]+$" }
     },
     "exclude": {
-      "description": "A list of repos to never mirror from this GitHub instance. Takes precedence over \"repos\" and \"repositoryQuery\" configuration.",
+      "description": "A list of repositories to never mirror from this GitHub instance. Takes precedence over \"repos\" and \"repositoryQuery\" configuration.",
       "type": "array",
       "minItems": 1,
       "items": {
@@ -49,12 +49,12 @@
         "anyOf": [{ "required": ["name"] }, { "required": ["id"] }],
         "properties": {
           "name": {
-            "description": "The name of a GitHub repo (\"owner/name\") to exclude from mirroring.",
+            "description": "The name of a GitHub repository (\"owner/name\") to exclude from mirroring.",
             "type": "string",
             "pattern": "^[\\w-]+/[\\w.-]+$"
           },
           "id": {
-            "description": "The id of a GitHub repo (as returned by the GitHub instance's API) to exclude from mirroring.",
+            "description": "The ID of a GitHub repository (as returned by the GitHub instance's API) to exclude from mirroring.",
             "type": "string",
             "minLength": 1
           }
@@ -86,7 +86,7 @@
       "type": "object",
       "properties": {
         "ttl": {
-          "description": "The TTL of how long to cache permissions data. This is 3 hours by default.\n\nDecreasing the TTL will increase the load on the code host API. If you have X repos on your instance, it will take ~X/100 API requests to fetch the complete list for 1 user.  If you have Y users, you will incur X*Y/100 API requests per cache refresh period.\n\nIf set to zero, Sourcegraph will sync a user's entire accessible repository list on every request (NOT recommended).",
+          "description": "The TTL of how long to cache permissions data. This is 3 hours by default.\n\nDecreasing the TTL will increase the load on the code host API. If you have X repositories on your instance, it will take ~X/100 API requests to fetch the complete list for 1 user.  If you have Y users, you will incur X*Y/100 API requests per cache refresh period.\n\nIf set to zero, Sourcegraph will sync a user's entire accessible repository list on every request (NOT recommended).",
           "type": "string",
           "default": "3h"
         }

schema/github_stringdata.go

@@ -136,24 +136,24 @@ export const GITHUB_EXTERNAL_SERVICE: ExternalServiceKindMetadata = {
     defaultDisplayName: 'GitHub',
     defaultConfig: `{
   // Use Ctrl+Space for completion, and hover over JSON properties for documentation.
-  // Configuration options are documented here:
-  // https://docs.sourcegraph.com/admin/external_service/github#configuration
+  // Docs: https://docs.sourcegraph.com/admin/external_service/github#configuration
 
-  "url": "https://github.com",
+  "url": "https://github.com", // change to use with GitHub Enterprise
 
-  // A token is required for access to private repos, but is also helpful for public repos
-  // because it grants a higher hourly rate limit to Sourcegraph.
-  // Create one with the repo scope at https://[your-github-instance]/settings/tokens/new
+  // Enter an access token to mirror GitHub repositories. Create one for GitHub.com at
+  // https://github.com/settings/tokens/new?scopes=repo&description=Sourcegraph
+  // (for GitHub Enterprise, replace github.com with your instance's hostname).
+  // The "repo" scope is required to mirror private repositories.
   "token": "",
 
   // An array of strings specifying which GitHub or GitHub Enterprise repositories to mirror on Sourcegraph.
-  // See https://docs.sourcegraph.com/admin/site_config/all#githubconnection-object for more details.
+  // See the repositoryQuery documentation at https://docs.sourcegraph.com/admin/external_service/github#configuration for details.
   "repositoryQuery": [
       "none"
+      // "org:sourcegraph"
   ],
 
-  // Sync public repositories from https://github.com by adding them to "repos".
-  // (This is not necessary for GitHub Enterprise instances)
+  // Sync specific repositories by name (in addition to those matched in the repositoryQuery).
   "repos": [
       // "sourcegraph/sourcegraph"
   ]