fix: edit doctor --help

messages/doctor.js

@@ -1,35 +1,32 @@
 module.exports = {
-  commandDescription: `Run the CLI doctor, which gathers CLI configuration data and runs diagnostic tests to discover and report potential problems in your environment.
+  commandDescription: `Gather CLI configuration data and run diagnostic tests to discover and report potential problems in your environment.
 
-The doctor can run a command for you in debug mode, writing both stdout and stderr to files that you can provide to Salesforce Support or attach to GitHub issues.
+When you run the doctor command without parameters, it first displays a diagnostic overview of your environment. It then writes a detailed diagnosis to a JSON file in the current directory. Use the --outputdir to specify a different directory. To run diagnostic tests on a specific plugin, use the --plugin parameter. If the plugin isn't listening to the doctor, then you get a warning.
 
-The doctor can create a new GitHub issue for the Salesforce CLI, attaching all doctor diagnostic results and command debug files.
+Use the --command parameter to run a specific command in debug mode; the doctor writes both stdout and stderr to *.log files that you can provide to Salesforce Customer Support or attach to a GitHub issue.
 
-Plugin providers can also implement their own doctor diagnostic tests by listening to the "sf-doctor" event and running plugin specific tests that will be included in the doctor diagnostics log.
+Plugin providers can also implement their own doctor diagnostic tests by listening to the "sf-doctor" event and running plugin specific tests that are then included in the doctor diagnostics log.
 `,
   flags: {
-    command: 'run the specified command in debug mode and write results to a file.',
-    newissue: 'create a new GitHub issue for the CLI, attaching doctor diagnostic results.',
-    plugin: 'run doctor command diagnostics for a specific plugin.',
+    command: 'command to run in debug mode ; results are written to a log file',
+    newissue: 'create a new GitHub issue and attach all diagnostic results',
+    plugin: 'specific plugin on which to run diagnostics ',
     outputdir: 'directory to save all created files rather than the current working directory',
   },
   examples: [
     `Run CLI doctor diagnostics:
     $ <%= config.bin %> doctor
-Run CLI doctor diagnostics and the specified command, writing debug output to a file:
+Run CLI doctor diagnostics and the specified command, and write the debug output to a file:
     $ <%= config.bin %> doctor --command "force:org:list --all"
 Run CLI doctor diagnostics for a specific plugin:
-    $ <%= config.bin %> doctor --plugin @salesforce/plugin-source
-Run CLI doctor diagnostics and create a new CLI GitHub issue, attaching all doctor diagnostics:
-    $ <%= config.bin %> doctor --newissue
-  `,
+    $ <%= config.bin %> doctor --plugin @salesforce/plugin-source`,
   ],
   pinnedSuggestions: {
-    checkGitHubIssues: 'check https://github.com/forcedotcom/cli/issues for community posted CLI issues',
-    checkSfdcStatus: 'check http://status.salesforce.com for any Salesforce announced problems',
+    checkGitHubIssues: 'Check https://github.com/forcedotcom/cli/issues for CLI issues posted by the community.',
+    checkSfdcStatus: 'Check http://status.salesforce.com for general Salesforce availability and performance.',
   },
-  doctorNotInitializedError: 'Must first initialize a new SfDoctor',
-  doctorAlreadyInitializedError: 'SfDoctor has already been initialized',
+  doctorNotInitializedError: 'Must first initialize a new SfDoctor.',
+  doctorAlreadyInitializedError: 'SfDoctor has already been initialized.',
   pluginNotInstalledError:
-    'Specified plugin [%s] is not installed. Please install it, correct the name, or choose another plugin.',
+    'Specified plugin [%s] isn\'t installed. Install it, correct the name, or choose another plugin.',
 };