Review and revise documentation language

docs/API.md

@@ -4,9 +4,10 @@
 Baby Buddy uses the [Django REST Framework](https://www.django-rest-framework.org/)
 (DRF) to provide a REST API.
 
-The only requirement for (most) requests is that the `Authorization` header is
+The only requirement for (most) requests is to set the `Authorization` header as
-set as described in the [Authentication](#authentication) section. The one
+described in the [Authentication](#authentication) section. The one exception is
-exception is the `/api` endpoint, which lists all available endpoints.
+the `/api` endpoint, which lists all available endpoints and does not require
+authorization.
 
 Currently, the following endpoints are available for `GET`, `OPTIONS`, and
 `POST` requests:
@@ -23,29 +24,28 @@ Currently, the following endpoints are available for `GET`, `OPTIONS`, and
 
 ## Authentication
 
-By default, the [TokenAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication)
+The [TokenAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#tokenauthentication)
 and [SessionAuthentication](https://www.django-rest-framework.org/api-guide/authentication/#sessionauthentication)
-classes are enabled. Session authentication covers local API requests made by
+are enabled by default. Session authentication covers local API requests made by
 the application itself. Token authentication allows external requests to be
 made.
 
 :exclamation: **In a production environment, token authentication should only
 be used for API calls to an `https` endpoint.** :exclamation:
 
-Each user is automatically assigned an API key that can be used for token
+Each user has an API key that can be used for token authentication. This key can
-authentication. This key can be found on the User Settings page for the logged
+be found on the User Settings page for the logged in the user. To use a key for
-in the user. To use a key for an API request, set the request `Authorization`
+an API request, set the request `Authorization` header to `Token <user-key>`. E.g.
-header to `Token <user-key>`. E.g.
 
     Authorization: Token 2h23807gd72h7hop382p98hd823dw3g665g56
 
-If the `Authorization` header is not set or the key is not valid, the API will
+If no `Authorization` header set, or the key is not valid the API will return
-return `403 Forbidden` with additional details in the response body.
+`403 Forbidden` with additional details in the response body.
 
 ## Schema
 
-API schema information in the [OpenAPI format](https://swagger.io/specification/)
+The API schema in [OpenAPI format](https://swagger.io/specification/) can be
-can be found in the [`openapi-schema.yml`](/openapi-schema.yml) file in the project
+found in the [`openapi-schema.yml`](/openapi-schema.yml) file in the project
 root. A live version is also available at the `/api/schema` path of a running
 instance.
 
@@ -166,27 +166,25 @@ formats.
 ### Timer Field
 
 The "timer" field is a special field available for `POST` operations to model
-endpoints supporting duration (Feeding, Sleep, Tummy Time). When the "timer"
+endpoints supporting duration (Feeding, Sleep, Tummy Time). Se the "timer"
-field is set in the request, the `start` and `end` fields will be filled in
+in a request to fill in the `start` and `end` fields automatically using the
-automatically using the `start` and `end` values *from the Timer* (the Timer
+`start` and `end` values *from the Timer* (the Timer will be stopped if it is
-will be stopped if it is currently running).
+currently running).
 
 Additionally, if the Timer has a Child relationship, the `child` field will be
 filled in automatically use the `child` value from the Timer.
 
-If the "timer" field is set, it's values will **always override** the relevant
+The "timer" field will **always override** the relevant fields (`child`, `start`,
-fields in the request. E.g. if a `POST` request is sent with both the `timer`
+and `end`) on the request. E.g., a `POST` request with both the `timer` and `end`
-and `end` fields, the value for the `end` field will be ignored and replaced by
+fields will ignore the `end` field value and replace it with the Timer's `end`
-the Timer's `end` value. The same applies for `start` and `child`. These fields
+value. The same applies for `start` and `child`. These fields are all **required**
-can all be left out of the request when the Timer is provided, otherwise they
+if the `timer` field is *not* set.
-are required fields.
 
 ### Response
 
 Returns JSON data in the response body describing the added/updated instance or
-error details if errors exist. Errors are keyed by either the field in error or
+error details keyed by either the field in error or the general string `non_field_errors`
-the general string `non_field_errors` (usually when validation involves
+(e.g., when validation involves multiple fields).
-multiple fields).
 
 ## `PATCH` Method
 
@@ -210,9 +208,8 @@ formats.
 ### Response
 
 Returns JSON data in the response body describing the added/updated instance or
-error details if errors exist. Errors are keyed by either the field in error or
+error details keyed by either the field in error or the general string `non_field_errors`
-the general string `non_field_errors` (usually when validation involves
+(e.g., when validation involves multiple fields).
-multiple fields).
 
 ## `DELETE` Method
 

docs/CONFIGURATION.md

@@ -29,9 +29,8 @@ take precedence over the contents of an `.env` file.**
 
 *Default: * (any)*
 
-This option may be set to a single host or comma-separated list of hosts
+Set this variable to a single host or comma-separated list of hosts without spaces.
-(without spaces). This should *always* be set to a specific host or hosts in
+This should *always* be set to a specific host or hosts in production deployments.
-production deployments.
 
 See also: [Django's documentation on the ALLOWED_HOSTS setting](https://docs.djangoproject.com/en/3.0/ref/settings/#allowed-hosts)
 
@@ -39,9 +38,8 @@ See also: [Django's documentation on the ALLOWED_HOSTS setting](https://docs.dja
 
 *Default: True*
 
-Whether or not to allow uploads (e.g. of Child photos). For some deployments
+Whether to allow uploads (e.g., of Child photos). For some deployments (Heroku)
-(AWS, Heroku) this setting will default to False due to the lack of available
+this setting will default to False due to the lack of available persistent storage.
-persistent storage.
 
 ## `AWS_ACCESS_KEY_ID`
 
@@ -66,7 +64,7 @@ See also: [`AWS_STORAGE_BUCKET_NAME`](#aws_storage_bucket_name)
 *Default: None*
 
 If you would like to use AWS S3 for storage on ephemeral storage platforms like
-Heroku you will need to create a bucket and add it's name. See django-storages'
+Heroku you will need to create a bucket and add its name. See django-storages'
 [Amazon S3 documentation](https://django-storages.readthedocs.io/en/latest/backends/amazon-S3.html).
 
 ## `DEBUG`
@@ -82,15 +80,15 @@ See also [Django's documentation on the DEBUG setting](https://docs.djangoprojec
 
 *Default: 18:00*
 
-The maximum *start* time (in the instance's time zone) before which a sleep
+The maximum nap *start* time (in the instance's time zone). Expects the 24-hour
-entry is consider a nap. Expects the 24-hour format %H:%M.
+format %H:%M.
 
 ## `NAP_START_MIN`
 
 *Default: 06:00*
 
-The minimum *start* time (in the instance's time zone) after which a sleep
+The minimum nap *start* time (in the instance's time zone). Expects the 24-hour
-entry is considered a nap. Expects the 24-hour format %H:%M.
+format %H:%M.
 
 ## `DB_ENGINE`
 
@@ -98,7 +96,7 @@ entry is considered a nap. Expects the 24-hour format %H:%M.
 
 The database engine utilized for the deployment.
 
-See also [Django's documentation on the ENGINE setting](https://docs.djangoproject.com/en/3.0/ref/settings/#engine) .
+See also [Django's documentation on the ENGINE setting](https://docs.djangoproject.com/en/3.0/ref/settings/#engine).
 
 ## `DB_HOST`
 
@@ -116,7 +114,8 @@ The name of the database table utilized for the deployment.
 
 *No Default*
 
-The password for the database user for the deployment. In the default example, this is the root PostgreSQL password.
+The password for the database user for the deployment. In the default example,
+this is the root PostgreSQL password.
 
 ## `DB_PORT`
 
@@ -143,9 +142,13 @@ See also [Django's documentation on the SECRET_KEY setting](https://docs.djangop
 
 *Default: None*
 
-If Baby Buddy is behind a proxy, you may need to set this to True. This tells Baby Buddy to trust the X-Forwarded-Proto header that comes from your proxy, and any time its value is 'https', then the request is guaranteed to be secure (i.e., it originally came in via HTTPS).
+If Baby Buddy is behind a proxy, you may need to set this to `True` in order to
+trust the `X-Forwarded-Proto` header that comes from your proxy, and any time
+its value is "https". This guarantees the request is secure (i.e., it originally
+came in via HTTPS).
 
-:warning: Modifying this setting can compromise Baby Buddy’s security. Ensure you fully understand your setup before changing it.
+:warning: Modifying this setting can compromise Baby Buddy’s security. Ensure
+you fully understand your setup before changing it.
 
 See also [Django's documentation on the SECURE_PROXY_SSL_HEADER setting](https://docs.djangoproject.com/en/3.0/ref/settings/#secure-proxy-ssl-header).
 
@@ -162,12 +165,12 @@ settings form.
 *Default: False*
 
 Whether to force 24-hour time format for locales that do not ordinarily use it
-(e.g. `en`). Support for this feature must implemented on a per-locale basis.
+(e.g. `en`). Support for this feature must be implemented on a per-locale basis.
 See format files under [`babybuddy/formats`](/babybuddy/formats) for supported
 locales.
 
-Note: This value for this setting is interpreted as a boolean from a string
+Note: Baby Buddy interprets this value as a boolean from a string
 using Python's built-in [`strtobool`](https://docs.python.org/3/distutils/apiref.html#distutils.util.strtobool)
-tool. Only certain strings are supported (e.g. "True" for `True` and "False" for
+tool. Only certain strings will work (e.g., "True" for `True` and "False" for
 `False`), other unrecognized strings will cause a `ValueError` and prevent Baby
 Buddy from loading.

docs/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 [Back to Table of Contents](/docs/TOC.md)
 
-Contributions are accepted and encouraged via GitHub [Issues](https://github.com/babybuddy/babybuddy/issues)
+Baby Buddy's maintainers accept and encourage contributions via GitHub [Issues](https://github.com/babybuddy/babybuddy/issues)
 and [Pull Requests](https://github.com/babybuddy/babybuddy/pulls). Maintainers
 and users may also be found at [babybuddy/Lobby](https://gitter.im/babybuddy/Lobby)
 on Gitter.
@@ -12,19 +12,18 @@ on Gitter.
 1. Make and commit tests for any new features or major functionality changes.
 1. Run `gulp lint` and `gulp test` (see [Gulp Commands](#gulp-commands)) and 
    ensure that all tests pass.
-1. If changes are made to assets: build, collect and commit the `/static` 
+1. Updated static assets if necessary and commit the `/static` folder (see [`gulp updatestatic`](#updatestatic)).
-   folder (see [`gulp collectstatic`](#collectstatic)).
 1. Open a [new pull request](https://github.com/babybuddy/babybuddy/compare) against
    the `master` branch.
    
-New pull requests will be reviewed by project maintainers as soon as possible 
+Maintainers will review new pull requests will as soon as possible, and we will
-and we will do our best to provide feedback and support potential contributors.
+do our best to provide feedback and support potential contributors.
 
 ## Translation
 
 ### POEditor
 
-Baby Buddy is set up as a project on [POEditor](https://poeditor.com/). 
+Baby Buddy uses [POEditor](https://poeditor.com/) for translation contributions. 
 Interested contributors can [join translation of Baby Buddy](https://poeditor.com/join/project/QwQqrpTIzn)
 for access to a simple, web-based frontend for adding/editing translation files
 to the project.
@@ -37,8 +36,8 @@ process will look something like this:
 1. Set up a development environment (see [Development](#development) below).
 
 1. Run `gulp makemessages -l xx` where `xx` is a specific locale code in the
-[ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g.
+[ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g.,
-"fr" for French or "es" for Spanish). This creates a new translation file at
+"il" for Italian or "es" for Spanish). This creates a new translation file at
 `locale/xx/LC_MESSAGES/django.po`, or updates one if it exists.
 
 1. Open the created/updated `django.po` file and update the header template
@@ -114,8 +113,8 @@ documentation section: [Translation](https://docs.djangoproject.com/en/3.0/topic
        export DJANGO_SETTINGS_MODULE=babybuddy.settings.development
 
     This process will differ based on the host OS. The above example is for
-    Linux-based systems. See [Configuration](#configuration) for other settings
+    Linux-based systems. See [Configuration](/docs/CONFIGURATION.md) for other
-    and methods for defining them.
+    settings and methods for defining them.
 
 1. Migrate the database
 
@@ -133,13 +132,14 @@ documentation section: [Translation](https://docs.djangoproject.com/en/3.0/topic
     restart the server as needed.
 
 Open [http://127.0.0.1:8000](http://127.0.0.1:8000) and log in with the default
-user name and password (`admin`/`admin`).
+username and password (`admin`/`admin`).
 
 ### Gulp commands
 
-Baby Buddy's Gulp commands are defined and configured by files in the
+[`gulpfile.js`](gulpfile.js) defines Baby Buddy's Gulp commands.
-[`gulpfile.js`](gulpfile.js) folder. Django's management commands are defined
+
-in the [`babybuddy/management/commands`](babybuddy/management/commands) folder.
+[`babybuddy/management/commands`](babybuddy/management/commands) defines Baby Buddy's
+management commands.
 
 - [`gulp`](#gulp)
 - [`gulp build`](#build)
@@ -165,7 +165,7 @@ in the [`babybuddy/management/commands`](babybuddy/management/commands) folder.
 
 Executes the `build` and `watch` commands and runs Django's development server.
 This command also accepts the special parameter `--ip` for setting the
-development server IP address. See [`gulp runserver`](#runserver) for details.
+server IP address. See [`gulp runserver`](#runserver) for details.
 
 #### `build`
 
@@ -248,7 +248,7 @@ Executes Django's `runserver` management task. Gulp passes non-overlapping
 arguments for this command.
 
 A special parameter, `--ip`, is also available to set the IP for the server.
-E.g execute `gulp runserver --ip 0.0.0.0:8000` to make the server available to
+E.g., execute `gulp runserver --ip 0.0.0.0:8000` to make the server available to
 other devices on your local network.
 
 #### `scripts`
@@ -285,8 +285,8 @@ order:
 - [`build`](#build)
 - [`collectstatic`](#collectstatic)
 
-This command should be executed, and any changes committed, any time changes
+Execute and commit changes made by this command whenever changing Baby Buddy's
-are made to Baby Buddy's frontend code (SASS, JS, etc.).
+frontend code (SASS, JS, etc.).
 
 ### Icon Font
 

docs/DEPLOYMENT.md

@@ -1,8 +1,8 @@
 # Deployment
 [Back to Table of Contents](/docs/TOC.md)
 
-The default user name and password for Baby Buddy is `admin`/`admin`. For any
+The default username and password for Baby Buddy is `admin`/`admin`. For any
-deployment, **log in and change the default admin password immediately**.
+deployment, **log in and change the default password immediately**.
 
 Many of Baby Buddy's configuration settings can be controlled using environment
 variables - see [Configuration](/docs/CONFIGURATION.md) for detailed information.
@@ -47,7 +47,7 @@ python3 /app/babybuddy/manage.py clearsessions
 
 [![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)
 
-For manual deployments to Heroku without using the deploy button, make sure to
+For manual deployments to Heroku without using the "deploy" button, make sure to
 create the following settings before pushing:
 
     heroku config:set DJANGO_SETTINGS_MODULE=babybuddy.settings.heroku
@@ -58,7 +58,7 @@ create the following settings before pushing:
 See [Configuration](/docs/CONFIGURATION.md) for other settings that can be controlled
 by `heroku config:set`.
 
-And after an initial push, execute the following commands:
+After an initial push, execute the following commands:
 
     heroku run python manage.py migrate
     heroku run python manage.py createcachetable
@@ -77,9 +77,9 @@ requirements are Python, a web server, an application server, and a database.
 
 ### Example deployment
 
-*This example assumes a 512MB VPS instance with Ubuntu 18.04.* It uses
+*This example assumes a 512 MB VPS instance with Ubuntu 18.04.* It uses Python 3.6+,
-Python 3.6+, nginx, uwsgi and sqlite and should be sufficient for a few users
+nginx, uwsgi and sqlite. It should be sufficient for a few users(e.g., two parents
-(e.g. two parents and 1+ child).
+and 1+ child).
 
 1. Install system packages
 

docs/IMPORT_EXPORT.md

@@ -36,9 +36,9 @@ be present for an import. Multiple file types -- including csv, xlsx, etc. --
 are supported for the import.
 
 The import pages do not provide *detailed* information about the required data
-and formats. When an import is attempted, all rows will be checked for errors
+and formats. All rows will be checked for errors on import and any issues will
-and any issues will be reported on screen and will need to be resolved before
+be reported on screen and will need to be resolved before the import can be
-the import can be performed.
+performed.
 
 See the [example import files](/core/tests/import) used for tests to get an idea
 of the expected data format.