comments on documentation (#17)

Co-authored-by: Owolabi Legunsen <[email protected]>

Author: owolabileg

doc/design.rst

@@ -6,9 +6,10 @@ Key design goal: Implement everything using functions and files (i.e.,
 there is no need to change existing shells or existing user code).
 
 As the result, a user can adopt gobash as needed without being forced
-to rewrite any of their code, but can benefit by using some/all of
-gobash features, which can be introduced gradually.  Additionally,
-gobash should work with any `bash` version and OS that runs `bash`.
+to rewrite any of their code. Rather, a user can benefit by using
+some/all of gobash features, which can be introduced gradually.
+Additionally, gobash should work with any `bash` version and OS that
+runs `bash`.
 
 .. toctree::
    :maxdepth: 2

doc/get-started.rst

@@ -29,8 +29,8 @@ Clone the gobash repository:
 
     git clone [email protected]:EngineeringSoftware/gobash
 
-Alternatively, you can avoid cloning the repo and directly source the
-library in your bash script:
+Alternatively, you can avoid cloning the repo and directly `source`
+the library in your bash script:
 
 .. code-block:: bash
 
@@ -107,8 +107,8 @@ In the following example (`point.sh`), we introduce a `struct` for a
 Test Example
 ------------
 
-This example illustrate a way to write tests using a testing package.
-The tests can be executed with the gobash tool.
+This example illustrates a way to write tests using gobash's testing
+package.  The tests can be executed with the gobash tool.
 
 We will extend the previous example to add tests (`point_test.sh`) for
 the function `point_add`.
@@ -134,7 +134,7 @@ Tests can be run with the following command:
 
     ./gobash test --paths point_test.sh --verbose
 
-The output of this execution will be along these lines:
+The output of this execution will look like this:
 
 .. code-block:: bash
 
@@ -151,7 +151,7 @@ There are a number of other examples that illustrate gobash in the
 `examples directory
 <https://github.com/EngineeringSoftware/gobash/tree/main/examples/README.md>`_.
 If you like learning by examples, that is the best place to go next.
-If you prefer to read higher level doc, then check
+If you prefer to read higher level documentation, then check
 :doc:`language`.
 
 .. toctree::

doc/index.rst

@@ -6,15 +6,16 @@ gobash is a set of bash functions that improve programming experience
 in bash (by providing collections, languages features, APIs, testing
 package, command line flag parsing, etc.) without modifying the shell
 interpreter(s). It works with any bash version (on Linux and
-Mac). Parts of the API are matching those in Go.
+Mac). Parts of the API match those in Go.
 
 gobash is publicly available on `GitHub
 <https://github.com/EngineeringSoftware/gobash>`_ under the
 `BSD-3-Clause license
-<https://github.com/EngineeringSoftware/gobash/blob/main/LICENSE>`_.
+<https://github.com/EngineeringSoftware/gobash/blob/main/LICENSE>`_. The
+dependencies needed to run gobash are listed on that GitHub page.
 
-Here is a quick example that uses gobash (but check later sections for
-a lot more):
+Here is a quick example that uses gobash (check later sections for
+more):
 
 .. code-block:: bash
 

doc/motivation.rst

@@ -10,13 +10,14 @@ of the scripting has moved over to Python (and a few other languages)
 due to availability of (standard) libraries and testing support.
 However, seeing `import subprocess; subprocess.run(["ls", "-l"])` or
 similar code in Python, and then using replacements for `awk`, `sed`,
-`grep`, `git` commands (and awkwardly processing their outputs) never
-looks very exciting.
+`grep`, `git` commands (and awkwardly processing their outputs)
+suggests that developers may use bash more if it had better libraries
+and testing support.
 
 Key motivation points:
 
 * Provide a "standard" library for bash
-* Provide missing language features (but do not design new language or change interpreters)
+* Provide missing language features (without designing a new language or changing interpreters)
 * Enable using the same set of functions across various operating systems
 * Enable using different interpreters (and their versions) by hiding details behind APIs