PHPORM-186 Review of GridFS docs

docs/filesystems.txt

@@ -47,7 +47,7 @@ to use the ``gridfs`` driver in ``config/filesystems.php``:
        ],
    ],
 
-You can configure the disk the following settings in ``config/filesystems.php``:
+You can configure the following settings in ``config/filesystems.php``:
 
 .. list-table::
    :header-rows: 1
@@ -60,7 +60,7 @@ You can configure the disk the following settings in ``config/filesystems.php``:
      - **Required**. Specifies the filesystem driver to use. Must be ``gridfs`` for MongoDB.
 
    * - ``connection``
-     - The database connection used to store jobs. It must be a ``mongodb`` connection. The driver uses the default connection if a connection is not specified.
+     - Database connection used to store jobs. It must be a ``mongodb`` connection. The driver uses the default connection if a connection is not specified.
 
    * - ``database``
      - Name of the MongoDB database for the GridFS bucket. The driver uses the database of the connection if a database is not specified.
@@ -71,7 +71,7 @@ You can configure the disk the following settings in ``config/filesystems.php``:
    * - ``prefix``
      - Specifies a prefix for the name of the files that are stored in the bucket. Using a distinct bucket is recommended
        in order to store the files in a different collection, instead of using a prefix.
-       The prefix should not start with a leading slash ``/``.
+       The prefix should not start with a leading slash (``/``).
 
    * - ``read-only``
      - If ``true``, writing to the GridFS bucket is disabled. Write operations will return ``false`` or throw exceptions
@@ -106,9 +106,10 @@ In this case, the options ``connection`` and ``database`` are ignored:
 Usage
 -----
 
-A benefit of using Laravel Filesystem is that it provides a common interface
-for all the supported file systems. You can use the ``gridfs`` disk in the same
-way as the ``local`` disk.
+Laravel Filesystem provides a common interface for all the supported file systems.
+You can use the ``gridfs`` disk in the same way as the ``local`` disk.
+
+The following example writes a file to the ``gridfs`` disk, then reads the file:
 
 .. code-block:: php
 
@@ -127,9 +128,10 @@ in the Laravel documentation.
 Versioning
 ----------
 
-File names in GridFS are metadata in file documents, which are identified by
-unique ObjectIDs. If multiple documents share the same file name, they are
-considered "revisions" and further distinguished by creation timestamps.
+GridFS creates file documents for each uploaded file. These documents contain
+metadata, including the file name and a unique ObjectId. If multiple documents
+share the same file name, they are considered "revisions" and further
+distinguished by creation timestamps.
 
 The Laravel MongoDB integration uses the GridFS Flysystem adapter. It interacts
 with file revisions in the following ways:
@@ -140,7 +142,7 @@ with file revisions in the following ways:
 - Deleting a file deletes all the revisions of this file name
 
 The GridFS Adapter for Flysystem does not provide access to a specific revision
-of a filename. You must use the
+of a file name. You must use the
 `GridFS API <https://www.mongodb.com/docs/php-library/current/tutorial/gridfs/>`__
 if you need to work with revisions, as shown in the following code:
 
@@ -155,5 +157,5 @@ if you need to work with revisions, as shown in the following code:
 
 .. note::
 
-   If you use a prefix the Filesystem component, you will have to handle it
-   by yourself when using the GridFS API directly.
+   If you specify the ``prefix`` Filesystem setting, you will have to explicitly
+   prepend the file names when using the GridFS API directly.