Docs review [#3083]

Some minor edits, after consultation w/ Pete, Kevin, and Leonid.

doc/sphinx-guides/source/api/native-api.rst

@@ -162,26 +162,26 @@ Import a Dataset into a Dataverse
 
 .. note:: This action requires a Dataverse account with super-user permissions.
 
-To import a dataset with an existing persistent identifier (pid), the dataset's metadata should be prepared in Dataverse's native JSON format. The pid can be provided in the JSON, or as a parameter at the URL. The following line imports a dataset with the pid ``PERSISTENT_IDENTIFIER`` to Dataverse, and then releases it::
+To import a dataset with an existing persistent identifier (PID), the dataset's metadata should be prepared in Dataverse's native JSON format. The PID can be provided in the JSON, or as a parameter at the URL. The following line imports a dataset with the PID ``PERSISTENT_IDENTIFIER`` to Dataverse, and then releases it::
 
   curl -H "X-Dataverse-key: $API_TOKEN" -X POST $SERVER_URL/api/dataverses/$DV_ALIAS/datasets/:import?pid=$PERSISTENT_IDENTIFIER&release=yes --upload-file dataset.json
 
 The ``pid`` parameter holds a persistent identifier (such as a DOI or Handle). If it is not present, Dataverse will try to get the PID from the JSON (using fields ``protocol``, ``authority``, and ``identifier`` of the top-level object). The import will fail if no PID is provided, or if the provided PID fails validation.
 
-The optional ``release`` parameter tells Dataverse to immediatly publish the dataset. If the parameter is changed to ``no``, the imported dataset will remain in ``DRAFT`` status.
+The optional ``release`` parameter tells Dataverse to immediately publish the dataset. If the parameter is changed to ``no``, the imported dataset will remain in ``DRAFT`` status.
 
 The JSON format is the same as that supported by the native API's :ref:`create dataset command<create-dataset-command>`, although it also allows packages.  For example:
 
 .. literalinclude:: ../../../../scripts/api/data/dataset-package-files.json
 
-The data files referenced by the ``POST``\ ed JSON should be placed in the dataset directory with filenames matching their specified storage identifiers. In installations using POSIX storage, these files must be made readable by glassfish.
+Before calling the API, make sure the data files referenced by the ``POST``\ ed JSON are placed in the dataset directory with filenames matching their specified storage identifiers. In installations using POSIX storage, these files must be made readable by GlassFish.
 
-.. tip:: It is preferable to avoid spaces and special characters in the storage identifer.
+.. tip:: If possible, it's best to avoid spaces and special characters in the storage identifier in order to avoid potential portability problems. The storage identifier corresponds with the filesystem name (or bucket identifier) of the data file, so these characters may cause unpredictability with filesystem tools.
 
 .. warning:: 
 
   * This API does not cover staging files (with correct contents, checksums, sizes, etc.) in the corresponding places in the Dataverse filestore.
-  * This API endpoint does not support importing files with persistent identifiers.
+  * This API endpoint does not support importing *files'* persistent identifiers.
   * A Dataverse server can import datasets with a valid PID that uses a different protocol or authority than said server is configured for. However, the server will not update the PID metadata on subsequent update and publish actions.