diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9a46c86..32ce1dc 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,147 +1,147 @@
-Content
+Contents
 
-* [code base](#code-base)
-* [config parsing](#config-parsing)
-  * [lower layer](#lower-layer)
-  * [higher layer](#higher-layer)
+* [Code base](#code-base)
+* [Config parsing](#config-parsing)
+  * [Lower layer](#lower-layer)
+  * [Higher layer](#higher-layer)
   * [Precedence](#precedence)
-  * [variables resolution](#variables-resolution)
-  * [rules](#rules)
-* [testing](#testing)
-  * [testing with unittest](#testing-with-unittest)
-  * [testing with bash scripts](#testing-with-bash-scripts)
-* [documentation](#documentation)
+  * [Variable resolution](#variable-resolution)
+  * [Rules](#rules)
+* [Testing](#testing)
+  * [Testing with unittest](#testing-with-unittest)
+  * [Testing with bash scripts](#testing-with-bash-scripts)
+* [Documentation](#documentation)
 
 Thanks for helping out!
 
-Feature requests, bug reports and PRs are always welcome!
+Feature requests, bug reports, and PRs are always welcome!
 
 This file provides a few pointers on how to contribute to dotdrop
-and where to find information. For any question, feel free to open an issue.
+and where to find information. For any questions, feel free to open an issue.
 
-For PR adding new features, I'd be very thankful if you could add either
+For PRs adding new features, I'd be very thankful if you could add either
 a unittest for the added feature or a bash script test (see [testing](#testing)), thanks!
 
-# code base
+# Code base
 
 Dotdrop's code base is located in the [dotdrop directory](/dotdrop).
 
-Here's an overview of the different files and their role:
+Here's an overview of the different files and their roles:
 
-* **action.py**: represent the actions and transformations
+* **action.py**: represents the actions and transformations
 * **cfg_yaml.py**: the lower level config parser (see [lower layer](#lower-layer))
 * **cfg_aggregator.py**: the higher level config parser (see [higher layer](#higher-layer))
 * **comparator.py**: the class handling the comparison for `compare`
 * **dictparser.py**: abstract class for parsing dictionaries
-* **dotdrop.py**: the entry point and where the different cli commands are executed
+* **dotdrop.py**: the entry point and where the different CLI commands are executed
 * **dotfile.py**: represent a dotfile
 * **installer.py**: the class handling the installation of dotfile for `install`
-* **jhelpers.py**: list of methods available in templates with jinja2
+* **jhelpers.py**: list of methods available in templates with Jinja2
 * **linktypes.py**: enum for the three types of linking (none, symlink, children)
 * **logger.py**: the custom logger
 * **options.py**: the class embedding all the different options across dotdrop
-* **profile.py**: represent a profile
-* **settings.py**: represent the config settings
-* **templategen.py**: the jinja2 templating class
+* **profile.py**: represents a profile
+* **settings.py**: represents the config settings
+* **templategen.py**: the Jinja2 templating class
 * **updater.py**: the class handling the update of dotfiles for `update`
 * **utils.py**: some useful methods used across the code base
 
-# config parsing
+# Config parsing
 
-The configuration file (yaml) is parsed using two layers:
+The configuration file (YAML) is parsed using two layers:
 
-  * first in the lower layer in [cfg_yaml.py](/dotdrop/cfg_yaml.py)
-  * then in the higher layer in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py)
+  * First in the lower layer in [cfg_yaml.py](/dotdrop/cfg_yaml.py)
+  * Then in the higher layer in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py)
 
 Only the higher layer is accessible to other classes of dotdrop.
 
-## lower layer
+## Lower layer
 
-This is done in [cfg_yaml.py](/dotdrop/cfg_yaml.py)
+This is done in [cfg_yaml.py](/dotdrop/cfg_yaml.py).
 
-The lower layer part is only taking care of basic types
+The lower layer part only takes care of basic types
 and does the following:
-  * normalize all config entries
-    * resolve paths (dotfiles src, dotpath, etc)
-    * refactor actions/transformations to a common format
-    * etc
-  * import any data from external files (configs, variables, etc)
-  * apply variable substitutions
-  * complete any data if needed (add the "profile" variable, etc)
-  * execute intrepreted variables through the shell
-  * write new entries (dotfile, profile) into the dictionary and save it to a file
-  * fix any deprecated entries (link_by_default, etc)
-  * clear empty entries
+  * Normalize all config entries
+    * Resolve paths (dotfiles src, dotpath, etc)
+    * Refactor actions/transformations to a common format
+    * Etc.
+  * Import any data from external files (configs, variables, etc)
+  * Apply variable substitutions
+  * Complete any data if needed (add the "profile" variable, etc)
+  * Execute intrepreted variables through the shell
+  * Write new entries (dotfile, profile) into the dictionary and save it to a file
+  * Fix any deprecated entries (link_by_default, etc)
+  * Clear empty entries
 
-In the end it builds a cleaned and normalized dictionary to be accessed by the higher layer.
+In the end, it builds a cleaned and normalized dictionary to be accessed by the higher layer.
 
-## higher layer
+## Higher layer
 
-This is done in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py)
+This is done in [cfg_aggregator.py](/dotdrop/cfg_aggregator.py).
 
 The higher layer will transform the dictionary parsed by the lower layer
 into objects (profiles, dotfiles, actions, transformations, etc).
-The higher layer has no notion of inclusion (profile included for example) or
-file importing (import actions, etc) or even interpreted variables
+The higher layer has no notion of inclusion (profile included, for example) or
+file importing (import actions etc.) or even interpreted variables
 (it only sees variables that have already been interpreted).
 
 It does the following:
-  * transform dictionaries into objects
-  * patch list of keys with its corresponding object (for example dotfile's actions)
-  * provide getters for every other classes of dotdrop needing to access elements
+  * Transform dictionaries into objects
+  * Patch lists of keys with their corresponding objects (For example, dotfile's actions)
+  * Provide getters for every dotdrop class that needs to access elements
 
-Note that any change to the yaml dictionary (adding a new profile or a new dotfile for
+Note that any changes to the YAML dictionary (adding a new profile or a new dotfile for
 example) won't be *seen* by the higher layer until the config is reloaded. Consider the
 `dirty` flag as a sign the file needs to be written and its representation in higher
 levels in not accurate anymore.
 
-## precedence
+## Precedence
 
 * `dynvariables` > `variables`
-* profile `(dyn)variables` > any other `(dyn)variables`
-* profile `(dyn)variables` > profile's included `(dyn)variables`
-* imported `variables`/`dynvariables` > `(dyn)variables`
+* Profile `(dyn)variables` > any other `(dyn)variables`
+* Profile `(dyn)variables` > profile's included `(dyn)variables`
+* Imported `variables`/`dynvariables` > `(dyn)variables`
 
-## variables resolution
+## Variable resolution
 
-How variables are resolved (through jinja2's
+How variables are resolved (through Jinja2's
 templating) in the config file.
 
-* resolve main config file variables
-  * merge `variables` and `dynvariables` (allowing cycling reference)
-  * recursively template merged `variables` and `dynvariables`
+* Resolve main config file variables
+  * Merge `variables` and `dynvariables` (allowing cyclic references)
+  * Recursively template merged `variables` and `dynvariables`
   * `dynvariables` are executed
-  * profile's `variables` and `dynvariables` are merged
-* resolve *included* entries (see below)
-  * paths and entries are templated
-    (allows to use something like `include {{@@ os @@}}.variables.yaml`)
+  * Profile's `variables` and `dynvariables` are merged
+* Resolve *included* entries (see below)
+  * Paths and entries are templated
+    (allows using something like `include {{@@ os @@}}.variables.yaml`)
 * *included* entries are processed
   * dyn-/variables are all resolved in their own file
 
-potential *included* entries
+Potential *included* entries:
 
-* entry *import_actions*
-* entry *import_configs*
-* entry *import_variables*
-* profile's *import*
-* profile's *include*
+* Entry *import_actions*
+* Entry *import_configs*
+* Entry *import_variables*
+* Profile's *import*
+* Profile's *include*
 
 Variables are then used to resolve different elements in the config file:
-see [this](docs/config.md#variables)
+see [this](docs/config.md#variables).
 
-## rules
+## Rules
 
 * `dynvariables` are executed in their own config file
-* since `variables` and `dynvariables` are templated before the `dynvariables`
-  are executed, this means that `dynvariables` can safely reference `variables` however
-  `variables` referencing `dynvariables` will result with the *not-executed* value of the
-  referenced `dynvariables` (see examples below)
-* profile cannot include profiles defined above in the import tree
-* config files do not have access to variables defined above in the import tree
-* actions/transformations using variables are resolved at runtime
-  (when action/transformation is executed) and not when loading the config
+* Since `variables` and `dynvariables` are templated before the `dynvariables`
+  are executed, this means that `dynvariables` can safely reference `variables`; however,
+  `variables` referencing `dynvariables` will result in the *not-executed* value of the
+  referenced `dynvariables` (see examples below).
+* Profiles cannot include profiles defined above in the import tree
+* Config files do not have access to variables defined above in the import tree
+* Actions/transformations using variables are resolved at runtime
+  (when the action/transformation is executed) and not when loading the config
 
-This will result with `dvar0 = "test"` and `var0 = "echo test"` (**not** `var0 = test`)
+This will result in `dvar0 = "test"` and `var0 = "echo test"` (**not** `var0 = test`):
 ```yaml
 variables:
   var0: "{{@@ dvar0 @@}}"
@@ -149,7 +149,7 @@ dynvariables:
   dvar0: "echo test"
 ```
 
-This will result with `dvar0 = "test"` and `var0 = "test"`
+This will result in `dvar0 = "test"` and `var0 = "test"`:
 ```yaml
 variables:
   var0: "test"
@@ -158,31 +158,31 @@ dynvariables:
 ```
 
 
-# testing
+# Testing
 
 Dotdrop is tested with the use of the [tests.sh](/tests.sh) script.
 
-* test for PEP8 compliance with `pycodestyle` and `pyflakes`
-* run the unittest available in [tests directory](/tests)
-* run the bash script tests in [tests-ng directory](tests-ng)
+* Test for PEP8 compliance with `pycodestyle` and `pyflakes`
+* Run the unittest available in [tests directory](/tests)
+* Run the bash script tests in [tests-ng directory](tests-ng)
 
-## testing with unittest
+## Testing with unittest
 
-All unittests are available in [tests directory](/tests)
-and use [python unittest](https://docs.python.org/3/library/unittest.html).
+All unittests are available in [the tests directory](/tests)
+and use [Python's unittest](https://docs.python.org/3/library/unittest.html).
 
 The file [helpers.py](/tests/helpers.py) provides different helper methods
 for the tests.
 
-## testing with bash scripts
+## Testing with bash scripts
 
 The bash scripts are available in [tests-ng directory](tests-ng).
 These test entire workflows by simulating the use of dotdrop from end to end
 for different use-cases (usually described in their filename or in the file header).
 
-Each script starts with the same boiler plate code that you can paste at the
+Each script starts with the same boilerplate code that you can paste at the
 start of your new test (see the head of the file down to `# this is the test`).
 
-# documentation
+# Documentation
 
 Dotdrop documentation is available under [https://dotdrop.readthedocs.io/](https://dotdrop.readthedocs.io/).
diff --git a/README.md b/README.md
index 008f600..68cb1f2 100644
--- a/README.md
+++ b/README.md
@@ -15,33 +15,33 @@
 *Save your dotfiles once, deploy them everywhere*
 
 [Dotdrop](https://github.com/deadc0de6/dotdrop) makes the management of dotfiles between different hosts easy.
-It allows to store your dotfiles on git and automagically deploy
+It allows you to store your dotfiles in Git and automagically deploy
 different versions of the same file on different setups.
 
-It also allows to manage different *sets* of dotfiles.
-For example you can have a set of dotfiles for your home laptop and
-a different set for your office desktop. Those sets may overlap and different
-versions of the same dotfiles can be deployed on different predefined *profiles*.
+It also allows you to manage different *sets* of dotfiles.
+For example, you can have a set of dotfiles for your home laptop and
+a different set for your office desktop. Those sets may overlap, and different
+versions of the same dotfiles can be deployed using different predefined *profiles*.
 Or you may have a main set of dotfiles for your
-everyday's host and a sub-set you only need to deploy to temporary
-hosts (cloud VM, etc) that may be using
+everyday host and a subset you only need to deploy to temporary
+hosts (cloud VM etc.) that may be using
 a slightly different version of some of the dotfiles.
 
 Features:
 
-* Sync once every dotfile on git for different usages
-* Allow dotfiles templating by leveraging [jinja2](https://palletsprojects.com/p/jinja/)
+* Sync once every dotfile in Git for different usages
+* Allow dotfile templating by leveraging [Jinja2](https://palletsprojects.com/p/jinja/)
 * Dynamically generated dotfile contents with pre-defined variables
 * Comparison between deployed and stored dotfiles
 * Handling multiple profiles with different sets of dotfiles
-* Easy import and update dotfiles
+* Easily import and update dotfiles
 * Handle files and directories
-* Support symlink of dotfiles
+* Support symlinking of dotfiles
 * Associate actions to the deployment of specific dotfiles
 * Associate transformations for storing encrypted/compressed dotfiles
 * Provide solutions for handling dotfiles containing sensitive information
 
-Check also the [blog post](https://deadc0de.re/articles/dotfiles.html),
+Also check out the [blog post](https://deadc0de.re/articles/dotfiles.html),
 the [example](#getting-started), the [documentation](https://dotdrop.readthedocs.io/) or
 how [people are using dotdrop](https://dotdrop.readthedocs.io/en/latest/misc/people-using-dotdrop/)
 for more.
@@ -56,16 +56,16 @@ pip3 install -r dotdrop/requirements.txt --user
 ./dotdrop.sh --help
 ```
 
-A mirror of this repository is available on gitlab under <https://gitlab.com/deadc0de6/dotdrop>.
+A mirror of this repository is available on GitLab under <https://gitlab.com/deadc0de6/dotdrop>.
 
-## Why dotdrop ?
+## Why dotdrop?
 
-There exist many tools to manage dotfiles however not
-many allow to deploy different versions of the same dotfile
-on different hosts. Moreover dotdrop allows to specify the
-set of dotfiles that need to be deployed on a specific profile.
+There exist many tools to manage dotfiles; however, not
+many allow you to deploy different versions of the same dotfile
+on different hosts. Moreover, dotdrop allows you to specify the
+set of dotfiles that need to be deployed for a specific profile.
 
-See the [example](#getting-started) for a concrete example on
+See the [example](#getting-started) for a concrete example of
 why [dotdrop](https://github.com/deadc0de6/dotdrop) rocks.
 
 ---
@@ -81,14 +81,14 @@ why [dotdrop](https://github.com/deadc0de6/dotdrop) rocks.
 
 There are multiple ways to install and use dotdrop.
 It is recommended to install dotdrop [as a submodule](#as-a-submodule)
-to your dotfiles git tree. Having dotdrop as a submodule guarantees that anywhere
-you are cloning your dotfiles git tree from you'll have dotdrop shipped with it.
+to your dotfiles Git tree. Having dotdrop as a submodule guarantees that anywhere
+you are cloning your dotfiles Git tree from you'll have dotdrop shipped with it.
 
-Below instructions show how to install dotdrop as a submodule. For alternative
-installation instructions see the
+The below instructions show how to install dotdrop as a submodule. For alternative
+installation instructions, see the
 [installation documentation](https://dotdrop.readthedocs.io/en/latest/installation/).
 
-Dotdrop is also available on
+Dotdrop is also available on:
 * pypi: https://pypi.org/project/dotdrop/
 * aur (stable): https://aur.archlinux.org/packages/dotdrop/
 * aur (git version): https://aur.archlinux.org/packages/dotdrop-git/
@@ -112,22 +112,22 @@ $ ./dotdrop/bootstrap.sh
 $ ./dotdrop.sh --help
 ```
 
-For MacOS users, make sure to install `realpath` through homebrew
+For macOS users, make sure to install `realpath` through Homebrew
 (part of *coreutils*).
 
-Using dotdrop as a submodule will need you to work with dotdrop by
+Using dotdrop as a submodule will require you to work with dotdrop by
 using the generated script `dotdrop.sh` at the root
 of your dotfiles repository. Note that this script updates the submodule
-automatically, unless called with the environment variable `DOTDROP_AUTOUPDATE`
+automatically unless called with the environment variable `DOTDROP_AUTOUPDATE`
 set to `no`.
 
 To ease the use of dotdrop, it is recommended to add an alias to it in your
-shell (*~/.bashrc*, *~/.zshrc*, etc) with the config file path, for example
+shell (*~/.bashrc*, *~/.zshrc*, etc.) with the config file path, for example:
 ```
 alias dotdrop='<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
 ```
 
-Completion scripts exist for `bash`, `zsh` and `fish`, see [the related doc](completion/README.md).
+Completion scripts exist for `bash`, `zsh` and `fish`; see [the related doc](completion/README.md).
 
 # Getting started
 
@@ -137,21 +137,21 @@ to store your dotfiles with dotdrop. *Init* or *clone* that new repository and
 
 Then import any dotfiles (files or directories) you want to manage with dotdrop.
 You can either use the default profile (which resolves to the *hostname* of the host
-you are running dotdrop on) or provide it specifically using the switch `-p --profile`.
+you are running dotdrop on) or provide it explicitly using the switch `-p`/`--profile`.
 
-Import dotfiles on host *home*
+Import dotfiles on host *home*:
 ```bash
 $ dotdrop import ~/.vimrc ~/.xinitrc ~/.config/polybar
 ```
 
 Dotdrop does two things:
 
-* Copy the dotfiles in the *dotpath* directory
+* Copy the dotfiles to the *dotpath* directory
   (defined in `config.yaml`, defaults to *dotfiles*)
 * Create the associated entries in the `config.yaml` file
   (in the `dotfiles` and `profiles` entries)
 
-Your config file will look something similar to this
+Your config file will look like something similar to this:
 ```yaml
 config:
   backup: true
@@ -186,16 +186,16 @@ see the [config doc](https://dotdrop.readthedocs.io/en/latest/config-format/).
 Commit and push your changes with git.
 
 Then go to another host where your dotfiles need to be managed as well,
-clone the previously setup repository
+clone the previously set up repository,
 and compare the local dotfiles with the ones stored in dotdrop:
 ```bash
 $ dotdrop compare --profile=home
 ```
 
-Now you might want to adapt the `config.yaml` file to your likings on
-that second host. Let's say for example that you only want `d_polybar` and
+Now you might want to adapt the `config.yaml` file to your liking on
+that second host. Let's say, for example, that you only want `d_polybar` and
 `f_xinitrc` to be deployed on that second host. You would then change your config
-to something like this (considering that the second host's hostname is *office*):
+to something like this (assuming that the second host's hostname is *office*):
 ```yaml
 …
 profiles:
@@ -211,9 +211,9 @@ profiles:
 ```
 
 Then adapt any dotfile using the [templating](https://dotdrop.readthedocs.io/en/latest/templating/)
-feature (if needed). For example you might want different fonts sizes on polybar for each host.
+feature (if needed). For example, you might want different fonts sizes in Polybar for each host.
 
-edit `<dotpath>/config/polybar/config`
+Edit `<dotpath>/config/polybar/config`:
 ```bash
 …
 {%@@ if profile == "home" @@%}
@@ -227,10 +227,10 @@ font2 = "unifont:size=6;0"
 ```
 
 You also want to have the correct interface set on the wireless network in
-the polybar config.
+the Polybar config.
 
 Add a [variable](https://dotdrop.readthedocs.io/en/latest/config/#variables)
-to the config file (with below example *home* gets the default `wlan0` value for
+to the config file (In the below example, *home* gets the default `wlan0` value for
 the variable `wifi` while *office* gets `wlp2s0`):
 ```yaml
 …
@@ -251,19 +251,19 @@ profiles:
       wifi: "wlp2s0"
 ```
 
-Then you can adapt the polybar config file so that the
-variable `wifi` gets correctly replaced during installation
+Then you can adapt the Polybar config file so that the
+variable `wifi` gets correctly replaced during installation:
 ```bash
 [module/wireless-network]
 type = internal/network
 interface = {{@@ wifi @@}}
 ```
 
-Also the home computer is running [awesomeWM](https://awesomewm.org/)
+Also, the home computer is running [awesomeWM](https://awesomewm.org/),
 and the office computer [bspwm](https://github.com/baskerville/bspwm).
 The `~/.xinitrc` file will therefore be different while still sharing some lines.
 
-edit `<dotpath>/xinitrc`
+Edit `<dotpath>/xinitrc`:
 ```bash
 #!/bin/bash
 
@@ -282,7 +282,7 @@ exec bspwm
 ```
 
 Finally you want everything installed with the *office* profile
-to be logged, you thus add an action to the config file:
+to be logged; you thus add an action to the config file:
 ```yaml
 …
 actions:
@@ -304,7 +304,7 @@ profiles:
       - loginstall "/tmp/dotdrop-installation.log"
 ```
 
-When done, you can install your dotfiles using
+When done, you can install your dotfiles using:
 ```bash
 $ dotdrop install
 ```
@@ -315,17 +315,17 @@ how your local dotfiles would be updated by dotdrop before running
 
 That's it, a single repository with all your dotfiles for your different hosts.
 
-For more see the [doc](https://dotdrop.readthedocs.io)
+For more, see the [docs](https://dotdrop.readthedocs.io):
 
-* [create actions](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-actions)
-* [use transformations](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-transformations)
-* [use variables](https://dotdrop.readthedocs.io/en/latest/config/#variables)
-* [symlink dotfiles](https://dotdrop.readthedocs.io/en/latest/config/#symlink-dotfiles)
+* [Create actions](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-actions)
+* [Use transformations](https://dotdrop.readthedocs.io/en/latest/config-details/#entry-transformations)
+* [Use variables](https://dotdrop.readthedocs.io/en/latest/config/#variables)
+* [Symlink dotfiles](https://dotdrop.readthedocs.io/en/latest/config/#symlink-dotfiles)
 * [and more](https://dotdrop.readthedocs.io/en/latest/howto/howto/)
 
 # Documentation
 
-Dotdrop's documentation is hosted on [readthedocs](https://dotdrop.readthedocs.io/en/latest/).
+Dotdrop's documentation is hosted on [Read the Docs](https://dotdrop.readthedocs.io/en/latest/).
 
 # Thank you
 
@@ -338,7 +338,7 @@ If you are having trouble installing or using dotdrop,
 
 If you want to contribute, feel free to do a PR (please follow PEP8).
 Have a look at the
-[contribution guidelines](https://github.com/deadc0de6/dotdrop/blob/master/CONTRIBUTING.md)
+[contribution guidelines](https://github.com/deadc0de6/dotdrop/blob/master/CONTRIBUTING.md).
 
 # License
 
diff --git a/completion/README.md b/completion/README.md
index 788c73e..3cf7e26 100644
--- a/completion/README.md
+++ b/completion/README.md
@@ -1,6 +1,6 @@
 Here are completion files for `bash`, `zsh` and `fish`
 for the use of dotdrop through the bash script `dotdrop.sh`
-or through the python script `dotdrop` (pypi, snap, setup.py, etc).
+or through the Python script `dotdrop` (PyPI, snap, setup.py, etc.).
 
 `bash` and `zsh` scripts are generated using
 [infi.docopt_completion](https://github.com/Infinidat/infi.docopt_completion).
@@ -9,15 +9,15 @@ or through the python script `dotdrop` (pypi, snap, setup.py, etc).
 
 Source the file
 
-* if using `dotdrop.sh` [dotdrop.sh-completion.bash](dotdrop.sh-completion.bash)
-* if using `dotdrop`: [dotdrop-completion.bash](dotdrop-completion.bash)
+* if using `dotdrop.sh`: [dotdrop.sh-completion.bash](dotdrop.sh-completion.bash)
+* If using `dotdrop`: [dotdrop-completion.bash](dotdrop-completion.bash)
 
 # zsh
 
-Copy the file in a path within `${fpath}`
+Copy the file to a path within `${fpath}`
 
-* if using `dotdrop.sh`: [_dotdrop.sh-completion.zsh](_dotdrop.sh-completion.zsh)
-* if using `dotdrop`: [_dotdrop-completion.zsh](_dotdrop-completion.zsh)
+* If using `dotdrop.sh`: [_dotdrop.sh-completion.zsh](_dotdrop.sh-completion.zsh)
+* If using `dotdrop`: [_dotdrop-completion.zsh](_dotdrop-completion.zsh)
 
 # fish
 
diff --git a/docs/README.md b/docs/README.md
index a1756d3..34eda1e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,21 +1,21 @@
 # Dotdrop
 
-[Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways of managing your dotfiles.
-It is especially powerful when it comes to managing those across different hosts.
+[Dotdrop](https://deadc0de.re/dotdrop/) is a dotfiles manager that provides efficient ways to manage your dotfiles.
+It is especially powerful when it comes to managing them across different hosts.
 
-The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with a different
+The idea of dotdrop is to have the ability to store each dotfile only once and deploy them with different
 content on different hosts/setups.
-To achieve this, it uses [jinja2](https://palletsprojects.com/p/jinja/) which is a templating engine that allows to specify
+To achieve this, it uses [Jinja2](https://palletsprojects.com/p/jinja/), which is a templating engine that allows you to specify
 during the dotfile installation how (with what content) each dotfile will be installed based on a selected profile.
 
-Most information on using dotdrop are described in this documentation
+Most information on using dotdrop is described in this documentation
 and in the [readme](https://github.com/deadc0de6/dotdrop/blob/master/README.md).
 
-For more check
+For more, check:
 
-* [a quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
-* [the blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
-* [an example](https://github.com/deadc0de6/dotdrop#getting-started)
-* [how people are using dotdrop](misc/people-using-dotdrop.md)
+* [A quick overview of dotdrop features](https://deadc0de.re/dotdrop/)
+* [The blogpost on dotdrop](https://deadc0de.re/articles/dotfiles.html)
+* [An example](https://github.com/deadc0de6/dotdrop#getting-started)
+* [How people are using dotdrop](misc/people-using-dotdrop.md)
 
-For more examples of config file, [search github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).
+For more examples of config file, [search GitHub](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code).
diff --git a/docs/config-details.md b/docs/config-details.md
index 48b28f4..2e1b839 100644
--- a/docs/config-details.md
+++ b/docs/config-details.md
@@ -1,13 +1,13 @@
 # Config details
 
-## Entry actions
+## actions entry
 
-Actions can be either `post` or `pre`
+Actions can be either `post` or `pre`.
 
-* `post` action will be executed after the dotfile deployment
-* `pre` action will be executed before the dotfile deployment
+* `post` action will be executed after the dotfile deployment.
+* `pre` action will be executed before the dotfile deployment.
 
-If you don't specify neither `post` nor `pre`, the action will be executed
+If you don't specify either `post` or `pre`, the action will be executed
 after the dotfile deployment (which is equivalent to `post`).
 Actions cannot obviously be named `pre` or `post`.
 
@@ -20,10 +20,10 @@ Four types of actions can be defined:
 
 **Notes**:
 
-* Any action with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords for example.
+* Any action with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example.
 * Make sure to quote your actions to avoid bad surprises
 * Actions are executed using the default shell (`$SHELL`)
-* To use shell variables in your actions you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
+* To use shell variables in your actions, you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
 
 ### Dotfile actions
 
@@ -31,13 +31,13 @@ It is sometimes useful to execute some kind of action
 when deploying a dotfile.
 
 Note that a dotfile's actions are only
-executed when the dotfile is installed (that is when
+executed when the dotfile is installed (that is, when
 the version present in dotdrop differs from the one
 in the filesystem).
 
-For example let's consider
-[Vundle](https://github.com/VundleVim/Vundle.vim) is used
-to manage vim's plugins, the following action could
+For example, let's consider
+[Vundle](https://github.com/VundleVim/Vundle.vim), used
+to manage Vim's plugins.  The following action could
 be set to update and install the plugins when `vimrc` is
 deployed:
 
@@ -60,7 +60,7 @@ profiles:
     - f_vimrc
 ```
 
-Thus when `f_vimrc` is installed, the command
+Thus, when `f_vimrc` is installed, the command
 `vim +VundleClean! +VundleInstall +VundleInstall! +qall` will
 be executed.
 
@@ -135,7 +135,7 @@ when xinitrc is installed.
 
 ### Default actions
 
-Dotdrop allows to execute an action for any dotfile installation. These actions work as any other action (`pre` or `post`).
+Dotdrop allows you to execute an action for any dotfile installation. These actions work as any other action (`pre` or `post`).
 
 For example, the below action will log each dotfile installation to a file.
 
@@ -161,8 +161,8 @@ profiles:
 
 ### Profile actions
 
-A profile action can be either `pre` or `post` action (see [actions](config-details.md#entry-actions)).
-Those are executed before any dotfile installation (for `pre`) and after all dotfiles installation (for `post`)
+A profile action can be either a `pre` or `post` action (see [actions](config-details.md#actions-entry)).
+These are executed before any dotfile installation (for `pre`) and after all dotfile installations (for `post`)
 only if at least one dotfile has been installed.
 
 ### Fake dotfile and actions
@@ -182,43 +182,43 @@ dotfiles:
     - always_action
 ```
 
-## Entry transformations
+## transformations entry
 
-For examples of transformation uses, see
+For examples of transformation uses, see:
 
 * [Handle compressed directories](howto/store-compressed-directories.md)
 * [Handle secrets](howto/sensitive-dotfiles.md)
 
 **Notes**:
 
-* Any transformation with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords for example.
+* Any transformation with a key starting with an underscore (`_`) won't be shown in output. This can be useful when working with sensitive data containing passwords, for example.
 * Make sure to quote your transformations to avoid bad surprises
 * Transformations are executed using the default shell (`$SHELL`)
 * To use shell variables in your transformations you need to escape the curly brackets (`${HOME}` becomes `${{HOME}}`)
 
 There are two types of transformations available:
 
-* **read transformations**: used to transform dotfiles before they are installed ([format](config-format.md) key `trans_read`)
+* **Read transformations**: used to transform dotfiles before they are installed ([format](config-format.md) key `trans_read`)
     * Used for commands `install` and `compare`
     * They have two arguments:
         * **{0}** will be replaced with the dotfile to process
         * **{1}** will be replaced with a temporary file to store the result of the transformation
-    * Happens **before** the dotfile is templated with jinja2 (see [templating](templating.md))
+    * Happens **before** the dotfile is templated with Jinja2 (see [templating](templating.md))
 
-* **write transformations**: used to transform files before updating a dotfile ([format](config-format.md) key `trans_write`)
+* **Write transformations**: used to transform files before updating a dotfile ([format](config-format.md) key `trans_write`)
     * Used for command `update`
     * They have two arguments:
         * **{0}** will be replaced with the file path to update the dotfile with
         * **{1}** will be replaced with a temporary file to store the result of the transformation
 
 A typical use-case for transformations is when dotfiles need to be
-stored encrypted or compressed. For more see [the howto](howto/howto.md).
+stored encrypted or compressed. For more, see [the howto](howto/howto.md).
 
-Note that transformations cannot be used if the dotfiles is to be linked (when `link: link` or `link: link_children`).
+Note that transformations cannot be used if the dotfile is to be linked (when `link: link` or `link: link_children`).
 
-Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations itself as well as its arguments can also be templated.
+Transformations also support additional positional arguments that must start from 2 (since `{0}` and `{1}` are added automatically). The transformations themselves as well as their arguments can also be templated.
 
-For example
+For example:
 ```yaml
 trans_read:
   targ: echo "$(basename {0}); {{@@ _dotfile_key @@}}; {2}; {3}" > {1}
@@ -233,14 +233,14 @@ profiles:
     - f_abc
 ```
 
-will result in `abc; f_abc; p1; lastarg`
+will result in `abc; f_abc; p1; lastarg`.
 
-## Entry variables
+## variables entry
 
 Variables defined in the `variables` entry are made available within the config file.
 
-Config variables are recursively evaluated what means that
-a config like the below
+Config variables are recursively evaluated, which means that
+a config like the below:
 ```yaml
 variables:
   var1: "var1"
@@ -265,9 +265,9 @@ will result in the following available variables:
 * dvar3: `dvar1 dvar2 dvar3`
 * dvar4: `var1 var2 var3`
 
-## Entry dynvariables
+## dynvariables entry
 
-It is also possible to have *dynamic* variables in the sense that their
+It is also possible to have *dynamic* variables, in the sense that their
 content will be interpreted by the shell before being substituted.
 
 These need to be defined in the config file under the entry `dynvariables`.
@@ -287,12 +287,12 @@ variables:
 
 They have the same properties as [Variables](config.md#variables).
 
-## Entry uservariables
+## uservariables entry
 
-If you want to manually enter variables values, you can use the
+If you want to manually enter variables' values, you can use the
 `uservariables` entry. Each variable will be prompted to the user.
 
-For example
+For example:
 ```yaml
 uservariables:
   emailvar: "email"
@@ -304,11 +304,11 @@ Please provide the value for "email":
 ```
 
 And store the entered text as the value for the variable `email`.
-The variable can then be used as any other [variables](config.md#variables).
+The variable can then be used as any other [variable](config.md#variables).
 
 `uservariables` are eventually saved to `uservariables.yaml` (relatively to the
 config file).
-This allow to use the following construct to prompt once for some specific variables and
+This allows you to use the following construct to prompt once for some specific variables and
 then store them in a file. You might also want to add `uservariables.yaml` to your `.gitignore`.
 ```yaml
 uservariables:
@@ -318,9 +318,9 @@ config:
     - uservariables.yaml:optional
 ```
 
-For an example, see [prompt user for variables](howto/prompt-user-for-variables.md)
+For an example, see [prompt user for variables](howto/prompt-user-for-variables.md).
 
-## Entry profile variables
+## Profile variables entry
 
 Profile variables will take precedence over globally defined variables.
 This means that you could do something like this:
@@ -342,7 +342,7 @@ profiles:
     - f_gitconfig
 ```
 
-## Entry profile include
+## Profile include entry
 
 If one profile is using the entire set of another profile, one can use
 the `include` entry to avoid redundancy.
@@ -364,9 +364,9 @@ profiles:
 ```
 Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
 
-For more advanced use-cases variables
+For more advanced use-cases, variables
 ([variables](config.md#variables) and [dynvariables](#entry-dynvariables))
-can be used to specify the profile to include in a profile
+can be used to specify the profile to include in a profile:
 
 For example:
 ```yaml
@@ -389,12 +389,12 @@ profiles:
     - "profile_{{@@ var1 @@}}"
 ```
 
-Note that profile cannot include other profiles defined above in
-the import tree (profile exists in another file and is imported using `import_configs` for example).
+Note that profiles cannot include other profiles defined above in
+the import tree (for example, when a profile exists in another file and is imported using `import_configs`).
 
-## Entry profile import
+## Profile import entry
 
-Profile's dotfiles list can be loaded from external files
+A profile's dotfiles list can be loaded from external files
 by specifying their paths in the config entry `import` under the specific profile.
 
 The paths can be absolute or relative to the config file location.
@@ -426,13 +426,13 @@ dotfiles:
   - f_xyz
 ```
 
-Variables can be used in `import` and would allow to do something like
+Variables can be used in `import`, which allow you to do something like:
 ```yaml
 import:
 - profiles.d/{{@@ profile @@}}.yaml
 ```
 
-## Entry import_variables
+## import_variables entry
 
 It is possible to load variables/dynvariables from external files by providing their
 paths in the config entry `import_variables`.
@@ -458,13 +458,13 @@ dynvariables:
 ```
 
 Dotdrop will fail if an imported path points to a non-existing file.
-It is possible to make non-existing paths not fatal by appending the path with `:optional`
+It is possible to make non-existing paths not fatal by appending `:optional` to the path:
 ```yaml
 import_variables:
 - variables.d/myvars.yaml:optional
 ```
 
-## Entry import_actions
+## import_actions entry
 
 It is possible to load actions from external files by providing their
 paths in the config entry `import_actions`.
@@ -497,13 +497,13 @@ External/imported variables will take precedence over variables defined
 inside the main config file.
 
 Dotdrop will fail if an imported path points to a non-existing file.
-It is possible to make non-existing paths not fatal by appending the path with `:optional`
+It is possible to make non-existing paths not fatal by appending `:optional` to the path:
 ```yaml
 import_actions:
 - actions.d/myactions.yaml:optional
 ```
 
-## Entry import_configs
+## import_configs entry
 
 Entire config files can be imported using the `import_configs` entry.
 This means making the following available from the imported config file in the original config file:
@@ -569,13 +569,13 @@ actions:
     show: less
 ```
 
-In this example `config.yaml` imports `other-config.yaml`. The dotfile `f_def`
+In this example, `config.yaml` imports `other-config.yaml`. The dotfile `f_def`
 used in the profile `my-host` is defined in `other-config.yaml`, and so is the
 profile `other-host` included from `my-haskell`. The action `show` is defined
 in `actions.yaml`, which is in turn imported by `other-config.yaml`.
 
 Dotdrop will fail if an imported path points to a non-existing file.
-It is possible to make non-existing paths not fatal by appending the path with `:optional`
+It is possible to make non-existing paths not fatal by appending `:optional` to the path.
 ```yaml
 import_configs:
 - other-config.yaml:optional
@@ -583,10 +583,10 @@ import_configs:
 
 ## Dynamic dotfile paths
 
-Dotfile source (`src`) and destination (`dst`) can be dynamically constructed using
+Dotfile source (`src`) and destination (`dst`) paths can be dynamically constructed using
 defined variables ([variables and dynvariables](config.md#variables)).
 
-For example to have a dotfile deployed on the unique firefox profile where the
+For example, to have a dotfile deployed on a unique Firefox profile where the
 profile path is dynamically found using a shell oneliner stored in a dynvariable:
 ```yaml
 dynvariables:
@@ -603,10 +603,10 @@ profiles:
 
 ## Dynamic dotfile link value
 
-Dotfile `link` value can be dynamically constructed using
-define variables ([variables and dynvariables](config.md#variables)).
+Dotfile `link` values can be dynamically constructed using
+defined variables ([variables and dynvariables](config.md#variables)).
 
-For example
+For example:
 ```yaml
 variables:
   link_value: "nolink"
diff --git a/docs/config-format.md b/docs/config-format.md
index 17c7aa9..322cc33 100644
--- a/docs/config-format.md
+++ b/docs/config-format.md
@@ -1,65 +1,65 @@
 # Config format
 
-Dotdrop config file uses [yaml](https://yaml.org/) syntax.
+The dotdrop config file uses [YAML](https://yaml.org/) syntax.
 
 Here is a minimal config file to start with:
 [config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
 
 ## config entry
 
-The **config** entry (mandatory) contains settings for the deployment
+The **config** entry (mandatory) contains settings for the deployment.
 
 Entry    | Description | Default
 -------- | ------------- | ------------
-`backup` | create a backup of the dotfile in case it differs from the one that will be installed by dotdrop  | true
-`banner` | display the banner  | true
-`cmpignore` | list of patterns to ignore when comparing, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
-`create` | create directory hierarchy when installing dotfiles if it doesn't exist | true
-`default_actions` | list of action's keys to execute for all installed dotfile (see [actions](config-details.md#entry-actions)) | -
-`diff_command` | the diff command to use for diffing files | `diff -r -u {0} {1}`
-`dotpath` | path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
-`filter_file` | list of paths to load templating filters from (see [Templating available filters](templating.md#template-filters)) | -
-`force_chmod` | if true, do not ask confirmation to apply permissions on install | false
-`func_file` | list of paths to load templating functions from (see [Templating available methods](templating.md#template-methods)) | -
-`ignore_missing_in_dotdrop` | ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing)) | false
-`ignoreempty` | do not deploy template if empty | false
-`impignore` | list of patterns to ignore when importing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
-`import_actions` | list of paths to load actions from (absolute path or relative to the config file location, see [Import actions from file](config-details.md#entry-import_actions)) | -
-`import_configs` | list of config file paths to be imported in the current config (absolute path or relative to the current config file location, see [Import config files](config-details.md#entry-import_configs)) | -
-`import_variables` | list of paths to load variables from (absolute path or relative to the config file location see [Import variables from file](config-details.md#entry-import_variables)) | -
-`instignore` | list of patterns to ignore when installing, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
-`keepdot` | preserve leading dot when importing hidden file in the `dotpath` | false
-`link_dotfile_default` | set dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
-`link_on_import` | set dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
-`longkey` | use long keys for dotfiles when importing (see [Import dotfiles](usage.md#import-dotfiles)) | false
-`minversion` | (*for internal use, do not modify*) provides the minimal dotdrop version to use | -
-`showdiff` | on install show a diff before asking to overwrite (see `--showdiff`) | false
-`template_dotfile_default` | disable templating on all dotfiles when set to false | true
-`upignore` | list of patterns to ignore when updating, apply to all dotfiles (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns)) | -
-`workdir` | path to the directory where templates are installed before being symlinked when using `link:link` or `link:link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop`
-<s>link_by_default</s> | when importing a dotfile set `link` to that value per default | false
+`backup` | Create a backup of the dotfile in case it differs from the one that will be installed by dotdrop  | true
+`banner` | Display the banner  | true
+`cmpignore` | List of patterns to ignore when comparing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
+`create` | Create a directory hierarchy when installing dotfiles if it doesn't exist | true
+`default_actions` | List of action keys to execute for all installed dotfiles (See [actions](config-details.md#actions-entry)) | -
+`diff_command` | The diff command to use for diffing files | `diff -r -u {0} {1}`
+`dotpath` | Path to the directory containing the dotfiles to be managed by dotdrop (absolute path or relative to the config file location) | `dotfiles`
+`filter_file` | List of paths to load templating filters from (See [Templating available filters](templating.md#template-filters)) | -
+`force_chmod` | If true, do not ask confirmation to apply permissions on install | false
+`func_file` | List of paths to load templating functions from (See [Templating available methods](templating.md#template-methods)) | -
+`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (See [Ignore missing](usage.md#ignore-missing)) | false
+`ignoreempty` | Do not deploy template if empty | false
+`impignore` | List of patterns to ignore when importing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
+`import_actions` | List of paths to load actions from (absolute path or relative to the config file location; see [Import actions from file](config-details.md#import_actions-entry)) | -
+`import_configs` | List of config file paths to be imported into the current config (absolute paths or relative to the current config file location; see [Import config files](config-details.md#import_configs-entry)) | -
+`import_variables` | List of paths to load variables from (absolute paths or relative to the config file location; see [Import variables from file](config-details.md#import_variables-entry)) | -
+`instignore` | List of patterns to ignore when installing, applied to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
+`keepdot` | Preserve leading dot when importing hidden file in the `dotpath` | false
+`link_dotfile_default` | Set a dotfile's `link` attribute to this value when undefined. Possible values: *nolink*, *link* (See [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
+`link_on_import` | Set a dotfile's `link` attribute to this value when importing. Possible values: *nolink*, *link* [Symlinking dotfiles](config.md#symlink-dotfiles)) | `nolink`
+`longkey` | Use long keys for dotfiles when importing (See [Import dotfiles](usage.md#import-dotfiles)) | false
+`minversion` | (*for internal use, do not modify*) Provides the minimal dotdrop version to use | -
+`showdiff` | On install, show a diff before asking to overwrite (See `--showdiff`) | false
+`template_dotfile_default` | Disable templating on all dotfiles when set to false | true
+`upignore` | List of patterns to ignore when updating, appled to all dotfiles (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns)) | -
+`workdir` | Path to the directory where templates are installed before being symlinked when using `link:link` or `link:link_children` (absolute path or relative to the config file location) | `~/.config/dotdrop`
+<s>link_by_default</s> | When importing a dotfile, set `link` to this value by default | false
 
 ## dotfiles entry
 
-The **dotfiles** entry (mandatory) contains a list of dotfiles managed by dotdrop
+The **dotfiles** entry (mandatory) contains a YAML object with subobjects for the dotfiles managed by dotdrop.  The entries in the subobjects are as follows:
 
 Entry    | Description
 -------- | -------------
-`dst` | where this dotfile needs to be deployed (dotfile with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote)
-`src` | dotfile path within the `dotpath` (dotfile with empty `src` are ignored and considered installed, can use `variables`, make sure to quote)
-`link` | define how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (see [Symlinking dotfiles](config.md#symlink-dotfiles)) (defaults to value of `link_dotfile_default`)
-`actions` | list of action keys that need to be defined in the **actions** entry below (see [actions](config-details.md#entry-actions))
-`chmod` | defines the file permissions in octal notation to apply during installation (see [permissions](config.md#permissions))
-`cmpignore` | list of patterns to ignore when comparing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
-`ignore_missing_in_dotdrop` | ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing))
-`ignoreempty` | if true empty template will not be deployed (defaults to value of `ignoreempty`)
-`instignore` | list of patterns to ignore when installing (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
-`template` | if false disable template for this dotfile (defaults to value of `template_dotfile_default`)
-`trans_read` | transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below, see [transformations](config-details.md#entry-transformations))
-`trans_write` | transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below, see [transformations](config-details.md#entry-transformations))
-`upignore` | list of patterns to ignore when updating (enclose in quotes when using wildcards, see [ignore patterns](config.md#ignore-patterns))
-<s>link_children</s> | replaced by `link: link_children`
-<s>trans</s> | replaced by `trans_read`
+`dst` | Where this dotfile needs to be deployed (dotfiles with empty `dst` are ignored and considered installed, can use `variables`, make sure to quote)
+`src` | Dotfile path within the `dotpath` (dotfiles with empty `src` are ignored and considered installed, can use `variables`, make sure to quote)
+`link` | Defines how this dotfile is installed. Possible values: *nolink*, *link*, *link_children* (See [Symlinking dotfiles](config.md#symlink-dotfiles)) (defaults to value of `link_dotfile_default`)
+`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry))
+`chmod` | Defines the file permissions in octal notation to apply during installation (See [permissions](config.md#permissions))
+`cmpignore` | List of patterns to ignore when comparing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
+`ignore_missing_in_dotdrop` | Ignore missing files in dotdrop when comparing and importing (see [Ignore missing](usage.md#ignore-missing))
+`ignoreempty` | If true, an empty template will not be deployed (defaults to the value of `ignoreempty`)
+`instignore` | List of patterns to ignore when installing (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
+`template` | If false, disable templating for this dotfile (defaults to the value of `template_dotfile_default`)
+`trans_read` | Transformation key to apply when installing this dotfile (must be defined in the **trans_read** entry below; see [transformations](config-details.md#transformations-entry))
+`trans_write` | Transformation key to apply when updating this dotfile (must be defined in the **trans_write** entry below; see [transformations](config-details.md#transformations-entry))
+`upignore` | List of patterns to ignore when updating (enclose in quotes when using wildcards; see [ignore patterns](config.md#ignore-patterns))
+<s>link_children</s> | Replaced by `link: link_children`
+<s>trans</s> | Replaced by `trans_read`
 
 ```yaml
 <dotfile-key-name>:
@@ -84,17 +84,16 @@ Entry    | Description
 
 ## profiles entry
 
-The **profiles** entry (mandatory) contains a list of profiles with the different dotfiles that
-  need to be managed
+The **profiles** entry (mandatory) contains a YAML object with subobjects for the profiles for the different dotfiles that need to be managed.  The entries in the subobjects are as follows:
 
 Entry    | Description
 -------- | -------------
-`dotfiles` | the dotfiles associated to this profile
-`import` | list of paths containing dotfiles keys for this profile (absolute path or relative to the config file location, see [Import profile dotfiles from file](config-details.md#entry-profile-import)).
-`include` | include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (see [Include dotfiles from another profile](config-details.md#entry-profile-include))
-`variables` | profile specific variables (see [Variables](config.md#variables))
-`dynvariables` | profile specific interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables))
-`actions` | list of action keys that need to be defined in the **actions** entry below (see [actions](config-details.md#entry-actions))
+`dotfiles` | The dotfiles associated with this profile
+`import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-details.md#profile-import-entry)).
+`include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-details.md#profile-include-entry))
+`variables` | Profile-specific variables (See [Variables](config.md#variables))
+`dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-details.md#dynvariables-entry))
+`actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-details.md#actions-entry))
 
 ```yaml
 <some-profile-name-usually-the-hostname>:
@@ -120,21 +119,21 @@ Entry    | Description
 
 ## actions entry
 
-The **actions** entry (optional) contains a list of actions (see [actions](config-details.md#entry-actions))
+The **actions** entry (optional) contains an actions mapping (See [actions](config-details.md#actions-entry)).
 
 ```yaml
 actions:
   <action-key>: <command-to-execute>
 ```
 
-*pre* actions
+*pre* actions:
 ```yaml
 actions:
   pre:
     <action-key>: <command-to-execute>
 ```
 
-*post* actions
+*post* actions:
 ```yaml
 actions:
   post:
@@ -143,7 +142,7 @@ actions:
 
 ## trans_read entry
 
-The **trans_read** entry (optional) contains a list of transformations (see [transformations](config-details.md#entry-transformations))
+The **trans_read** entry (optional) contains a transformations mapping (See [transformations](config-details.md#transformations-entry)).
 
 ```yaml
 trans_read:
@@ -152,7 +151,7 @@ trans_read:
 
 ## trans_write entry
 
-The **trans_write** entry (optional) contains a list of write transformations (see [transformations](config-details.md#entry-transformations))
+The **trans_write** entry (optional) contains a write transformations mapping (See [transformations](config-details.md#transformations-entry)).
 
 ```yaml
 trans_write:
@@ -161,7 +160,7 @@ trans_write:
 
 ## variables entry
 
-The **variables** entry (optional) contains a list of variables (see [variables](config.md#variables))
+The **variables** entry (optional) contains a variables mapping (See [variables](config.md#variables)).
 
 ```yaml
 variables:
@@ -170,8 +169,8 @@ variables:
 
 ## dynvariables entry
 
-The **dynvariables** entry (optional) contains a list of interpreted variables
-(see [Interpreted variables](config-details.md#entry-dynvariables))
+The **dynvariables** entry (optional) contains an interpreted variables mapping
+(See [Interpreted variables](config-details.md#dynvariables-entry)).
 
 ```yaml
 dynvariables:
@@ -180,9 +179,9 @@ dynvariables:
 
 ## uservariables entry
 
-The **uservariables** entry (optional) contains a list of variables
-to be queried to the user for their values.
-(see [User variables](config-details.md#entry-uservariables))
+The **uservariables** entry (optional) contains a collection of variables
+whose values are queried from the user
+(See [User variables](config-details.md#uservariables-entry)).
 
 ```yaml
 uservariables:
diff --git a/docs/config.md b/docs/config.md
index 7990b33..e45e8a5 100644
--- a/docs/config.md
+++ b/docs/config.md
@@ -5,73 +5,73 @@
 The config file used by dotdrop is
 [config.yaml](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml).
 
-Unless specified dotdrop will look in following places for its config file
-and use the first one found
+Unless specified otherwise, dotdrop will look in the following places for its config file
+and use the first one found:
 
-* current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) is located if used
+* Current/working directory or the directory where [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) is located if used
 * `${XDG_CONFIG_HOME}/dotdrop/`
 * `~/.config/dotdrop/`
 * `/etc/xdg/dotdrop/`
 * `/etc/dotdrop/`
 
-You can force dotdrop to use a different file either by using the `-c --cfg` cli switch
+You can force dotdrop to use a different file either by using the `-c`/`--cfg` CLI switch
 or by defining the `DOTDROP_CONFIG` environment variable.
 
 ## Variables
 
 Multiple variables can be used within the config file to
-parametrize following elements of the config:
+parametrize the following elements of the config:
 
-* dotfiles `src` and `dst` paths (see [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths))
-* external path specifications
+* Dotfile `src` and `dst` paths (See [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths))
+* External path specifications
   * `import_variables`
   * `import_actions`
   * `import_configs`
-  * profiles's `import`
-  * profiles's `include`
+  * Profiles' `import`
+  * Profiles' `include`
 
-`actions` and `transformations` also support the use of variables
+`actions` and `transformations` also support the use of variables,
 but those are resolved when the action/transformation is executed
-(see [Dynamic actions](config-details.md#dynamic-actions),
+(See [Dynamic actions](config-details.md#dynamic-actions),
 [Dynamic transformations](config-details.md#dynamic-transformations) and [Templating](templating.md)).
 
-Following variables are available in the config files:
+The following variables are available in the config files:
 
-* [variables defined in the config](config-details.md#entry-variables)
-* [interpreted variables defined in the config](config-details.md#entry-dynvariables)
-* [user variables defined in the config](config-details.md#entry-uservariables)
-* [profile variables defined in the config](config-details.md#entry-profile-variables)
-* environment variables: `{{@@ env['MY_VAR'] @@}}`
-* dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
+* [Variables defined in the config](config-details.md#entry-variables)
+* [Interpreted variables defined in the config](config-details.md#entry-dynvariables)
+* [User variables defined in the config](config-details.md#entry-uservariables)
+* [Profile variables defined in the config](config-details.md#entry-profile-variables)
+* Environment variables: `{{@@ env['MY_VAR'] @@}}`
+* Dotdrop header: `{{@@ header() @@}}` (see [Dotdrop header](templating.md#dotdrop-header))
 
-As well as all [template methods](templating.md#template-methods) and [template filters](templating.md#template-filters).
+as well as all [template methods](templating.md#template-methods) and [template filters](templating.md#template-filters).
 
 Note that all variables available in the config file will
 then be available during [templating](templating.md).
 
 Here are some rules on the use of variables in configs:
 
-* [interpreted variables](config-details.md#entry-dynvariables) are executed in their own file
-* [interpreted variables](config-details.md#entry-dynvariables) and
+* [Interpreted variables](config-details.md#entry-dynvariables) are executed in their own file.
+* [Interpreted variables](config-details.md#entry-dynvariables) and
   [variables](config-details.md#entry-variables) are templated before
-  [interpreted variables](config-details.md#entry-dynvariables) are executed
-* config files do not have access to variables defined above in the import tree
-* `dynvariables` take precedence over `variables`
-* profile `(dyn)variables` take precedence over any other `(dyn)variables`
-* profile `(dyn)variables` take precedence over profile's included `(dyn)variables`
-* external/imported `(dyn)variables` take precedence over
-  `(dyn)variables` defined inside the main config file
-* [user variables](config-details.md#entry-uservariables) are ignored if
-  any other variable with the same key is defined
+  [interpreted variables](config-details.md#entry-dynvariables) are executed.
+* Config files do not have access to variables defined above in the import tree.
+* `dynvariables` take precedence over `variables`.
+* Profile `(dyn)variables` take precedence over any other `(dyn)variables`.
+* Profile `(dyn)variables` take precedence over profile's included `(dyn)variables`.
+* External/imported `(dyn)variables` take precedence over
+  `(dyn)variables` defined inside the main config file.
+* [User variables](config-details.md#entry-uservariables) are ignored if
+  any other variable with the same key is defined.
 
 ## Permissions
 
-Dotdrop allows to control the permissions applied to a dotfile using the
+Dotdrop allows you to control the permissions applied to a dotfile using the
 config dotfile entry [chmod](config-format.md#dotfiles-entry).
 A [chmod](config-format.md#dotfiles-entry) entry on a directory
 is applied to the directory only, not recursively.
 
-For example
+For example:
 ```yaml
 dotfiles:
   f_file:
@@ -84,59 +84,59 @@ dotfiles:
     chmod: 744
 ```
 
-On `import` the following rules are applied:
+On `import`, the following rules are applied:
 
-* if the `-m --preserve-mode` switch is provided the imported file permissions are
+* If the `-m`/`--preserve-mode` switch is provided, the imported file's permissions are
   stored in a `chmod` entry
-* if imported file permissions differ from umask then its permissions are automatically
-  stored in the `chmod` entry
-* otherwise no `chmod` entry is added
+* If the imported file's permissions differ from the umask, then the permissions are automatically
+  stored in the `chmod` entry.
+* Otherwise, no `chmod` entry is added
 
-On `install` the following rules are applied:
+On `install`, the following rules are applied:
 
-* if `chmod` is specified in the dotfile, it will be applied to the installed dotfile
-* otherwise the permissions of the dotfile in the `dotpath` are applied.
-* if the global setting `force_chmod` is set to true dotdrop will not ask
-  for confirmation to apply permission
+* If `chmod` is specified in the dotfile, it will be applied to the installed dotfile.
+* Otherwise, the permissions of the dotfile in the `dotpath` are applied.
+* If the global setting `force_chmod` is set to true, dotdrop will not ask
+  for confirmation to apply permissions.
 
 On `update`:
 
-* if the permissions of the file in the filesystem differ from the dotfile in the `dotpath`
-  then the dotfile entry `chmod` is added/updated accordingly
+* If the permissions of the file in the filesystem differ from the dotfile in the `dotpath`,
+  then the dotfile entry `chmod` is added/updated accordingly.
 
 
-## Symlink dotfiles
+## Symlinking dotfiles
 
-Dotdrop is able to install dotfiles in three different ways
+Dotdrop is able to install dotfiles in three different ways,
 which are controlled by the `link` config attribute of each dotfile:
 
-* `link: nolink`: the dotfile (file or directory) is copied to its destination
-* `link: link`: the dotfile (file or directory) is symlinked to its destination
-* `link: link_children`: the files/directories found under the dotfile (directory) are symlinked to their destination
+* `link: nolink`: The dotfile (file or directory) is copied to its destination
+* `link: link`: The dotfile (file or directory) is symlinked to its destination
+* `link: link_children`: The files/directories found under the dotfile (directory) are symlinked to their destination
 
-For more see [this how-to](howto/symlink-dotfiles.md)
+For more, see [this how-to](howto/symlink-dotfiles.md).
 
 ## Template config entries
 
-Some entries in the config can use the templating feature (see [templating](templating.md)):
+Some entries in the config can use the templating feature (See [templating](templating.md)):
 
 Entry    | Related doc
 -------- | -------------
-dotfile src | [dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
-dotfile dst | [dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
-dotfile link | [dynamic dotfile link value](config-details.md#dynamic-dotfile-link-value)
-variables | [variables](config-details.md#entry-variables)
-dynvariables | [dynvariables](config-details.md#entry-dynvariables)
+dotfile src | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
+dotfile dst | [Dynamic dotfile paths](config-details.md#dynamic-dotfile-paths)
+dotfile link | [Dynamic dotfile link value](config-details.md#dynamic-dotfile-link-value)
+variables | [variables](config-details.md#variables-entry)
+dynvariables | [dynvariables](config-details.md#dynvariables-entry)
 actions | [dynamic actions](config-details.md#dynamic-actions)
-profile include | [profile include](config-details.md#entry-profile-include)
-profile import | [profile import](config-details.md#entry-profile-import)
-import_variables | [import_variables](config-details.md#entry-import_variables)
-import_actions | [import_actions](config-details.md#entry-import_actions)
-import_configs | [import_configs](config-details.md#entry-import_configs)
+profile include | [Profile include](config-details.md#profile-include-entry)
+profile import | [Profile import](config-details.md#profile-import-entry)
+import_variables | [import_variables](config-details.md#import_variables-entry)
+import_actions | [import_actions](config-details.md#import_actions-entry)
+import_configs | [import_configs](config-details.md#import_configs-entry)
 
 ## All dotfiles for a profile
 
-To use all defined dotfiles for a profile, simply use
+To use all defined dotfiles in a profile, simply use
 the keyword `ALL`.
 
 For example:
@@ -161,27 +161,27 @@ profiles:
 
 It is possible to ignore specific patterns when using dotdrop.
 
-* for [install](usage.md#install-dotfiles)
-    * using `instignore` in the config file
-* for [import](usage.md#import-dotfiles)
-    * using `impignore` in the config file
-* for [compare](usage.md#compare-dotfiles)
-    * using `cmpignore` in the config file
-    * using the command line switch `-i --ignore`
-* for [update](usage.md#update-dotfiles)
-    * using `upignore` in the config file
-    * using the command line switch `-i --ignore`
+* For [install](usage.md#install-dotfiles):
+    * Using `instignore` in the config file
+* For [import](usage.md#import-dotfiles):
+    * Using `impignore` in the config file
+* For [compare](usage.md#compare-dotfiles):
+    * Using `cmpignore` in the config file
+    * Using the command line switch `-i`/`--ignore`
+* For [update](usage.md#update-dotfiles):
+    * Using `upignore` in the config file
+    * Using the command line switch `-i`/`--ignore`
 
-The ignore pattern must follow Unix shell-style wildcards like for example `*/path/to/file`.
-Make sure to quote those when using wildcards in the config file.
+The ignore pattern must follow Unix shell-style wildcards, like, for example `*/path/to/file`.
+Make sure to quote these when using wildcards in the config file.
 
-Patterns used on a specific dotfile can be specified relative to the dotfile destination (`dst`).
+Patterns used for a specific dotfile can be specified relative to the dotfile destination (`dst`).
 
 Similar to a `.gitignore` file, you can prefix ignore patterns with an exclamation point (`!`).
 This so-called "negative ignore pattern" will cause any files that match that pattern to __not__ be ignored,
 provided they *would have* been ignored by an earlier ignore pattern (dotdrop will warn if that is not the
 case). This feature allows you to, for example, ignore all files within a certain directory, except for one
-particular one (see example below).
+particular one (See example below).
 
 ```yaml
 config:
@@ -212,7 +212,7 @@ dotfiles:
     - "*"
 ```
 
-To ignore specific directory when updating
+To ignore a specific directory when updating:
 ```yaml
 dotfiles:
   d_colorpicker:
@@ -222,7 +222,7 @@ dotfiles:
       - '*sub_directory_to_ignore'
 ```
 
-To ignore specific file `testfile` and directory `testdir` when importing:
+To ignore a specific file `testfile` and directory `testdir` when importing:
 ```yaml
 config:
   impignore:
diff --git a/docs/howto/append.md b/docs/howto/append.md
index 8e5590f..1072acb 100644
--- a/docs/howto/append.md
+++ b/docs/howto/append.md
@@ -23,9 +23,9 @@ actions:
   post:
     append: "cat {0} >> {1}; rm -f {0}"
 ```
-During installation, the `strip` action is executed before the installation and strips everything from the pattern `# my pattern` to the end of the file. Then the dotfile `somefile` is installed in a temporary location (here `tmpfile`) and finally the post action `append` will append the content of the `tmpfile` to the final dotfile pointed by `somefile_final`
+During installation, the `strip` action is executed before the installation, and it strips everything from the pattern `# my pattern` to the end of the file. Then the dotfile `somefile` is installed in a temporary location (here `tmpfile`) and finally the post action `append` will append the contents of the `tmpfile` to the final dotfile pointed to by `somefile_final`.
 
-Obviously the dotfile in the dotpath should start with a unique pattern (here `# my pattern`):
+Obviously, the dotfile in the dotpath should start with a unique pattern (here `# my pattern`):
 ```
 # my pattern
 this is the end
diff --git a/docs/howto/create-special-files.md b/docs/howto/create-special-files.md
index 50965af..93524b6 100644
--- a/docs/howto/create-special-files.md
+++ b/docs/howto/create-special-files.md
@@ -1,9 +1,9 @@
 # Create files on install
 
-One way for creating symlinks (or any other special files) is to use a combination of
+One way to create symlinks (or any other special file) is to use a combination of
 [actions](../config-details.md#entry-actions) and a *fake* dotfile.
 
-Let's say for example you have a list of directories you want to link
+Let's say, for example, you have a list of directories you want to link
 from under `~/.original` to `~/symlinks`.
 ```bash
 $ tree ~/.original
@@ -13,19 +13,19 @@ $ tree ~/.original
 └── dir3
 ```
 
-First you would store these directories names in a text file in your `<dotpath>/links.txt`
+First you would store these directory names in a text file in your `<dotpath>/links.txt`:
 ```
 dir1
 dir2
 dir3
 ```
 
-The config file would contain different elements
+The config file would contain different elements:
 
-* a `dynvariables` that will read the above text file
-* a few `variables` for the source and destination
-* an action that will create the destination directory and symlink those directories
-* a *fake* dotfile (with no `src` and no `dst` values) that will be always installed with the above action
+* A `dynvariables` that will read the above text file
+* A few `variables` for the source and destination
+* An action that will create the destination directory and symlink those directories
+* A *fake* dotfile (with no `src` and no `dst` values) that will be always installed with the above action
 
 ```yaml
 dynvariables:
@@ -45,7 +45,7 @@ actions:
       - symlink_them '{{@@ links_list @@}}' '{{@@ links_dst @@}}'
 ```
 
-The result would be
+The result would be:
 ```bash
 $ tree ~/.symlinks
 /home/user/.symlinks
@@ -54,4 +54,4 @@ $ tree ~/.symlinks
 └── dir3 -> /home/user/.original/dir3
 ```
 
-For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243)
+For reference, see [issue 243](https://github.com/deadc0de6/dotdrop/issues/243).
diff --git a/docs/howto/howto.md b/docs/howto/howto.md
index bf066a2..0dae537 100644
--- a/docs/howto/howto.md
+++ b/docs/howto/howto.md
@@ -1,4 +1,4 @@
-# HowTo
+# How To
 
 ## Append text to a dotfile on install
 
@@ -20,13 +20,13 @@
 
 [Handle special chars](special-chars.md)
 
-## Improve git integration
+## Improve Git integration
 
-[Improve git integration](improve-git-integration.md)
+[Improve Git integration](improve-git-integration.md)
 
-## Include file or template in template
+## Include files or templates in templates
 
-[Include file or template in template](include-in-template.md)
+[Include files or templates in templates](include-in-template.md)
 
 ## Manage system dotfiles
 
diff --git a/docs/howto/improve-git-integration.md b/docs/howto/improve-git-integration.md
index 8108dc8..7aec6ca 100644
--- a/docs/howto/improve-git-integration.md
+++ b/docs/howto/improve-git-integration.md
@@ -1,6 +1,6 @@
-# Improve git integration
+# Improve Git integration
 
-The below aliases can help with the process of updating your dotfiles between multiple hosts. Add those to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
+The below aliases can help with the process of updating your dotfiles between multiple hosts. Add them to your `~/.zshrc` or `~/.bashrc`. You can then simply run `dotsync` to push or pull from your dotfile repository.
 
 ```
 # Your dotdrop git repository location
@@ -11,4 +11,4 @@ alias dotgit="git -C $DOTREPO"
 alias dotsync="dotgit pull && dotgit add -A && dotgit commit && dotgit push; dotdrop install"
 ```
 
-Provided by [ReekyMarko](https://github.com/ReekyMarko)
+Provided by [ReekyMarko](https://github.com/ReekyMarko).
diff --git a/docs/howto/include-in-template.md b/docs/howto/include-in-template.md
index 35e6d5e..615f311 100644
--- a/docs/howto/include-in-template.md
+++ b/docs/howto/include-in-template.md
@@ -1,6 +1,6 @@
-# Include file or template in template
+# Include files or templates in templates
 
-[Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#include) for more. The path must be relative to the `dotpath`.
+[Jinja2](https://jinja.palletsprojects.com/en/2.11.x/templates/) provides the ability to include an external file/template from within a template with the directive `include`. See the [related docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#include) for more. The path must be relative to the `dotpath`.
 
 For example:
 ```yaml
diff --git a/docs/howto/merge-files-when-installing.md b/docs/howto/merge-files-when-installing.md
index a3a3c0f..31498ae 100644
--- a/docs/howto/merge-files-when-installing.md
+++ b/docs/howto/merge-files-when-installing.md
@@ -1,14 +1,14 @@
 # Merge files on install
 
-Dotdrop allows to merge multiple files into one using the jinja2's `include` directive.
+Dotdrop allows you to merge multiple files into one using Jinja2's `include` directive.
 
-For example let's consider you want to keep your `vimrc` split into multiple parts in dotdrop
+For example, let's assume you want to keep your `.vimrc` split into multiple parts in dotdrop:
 * `<dotpath>/vimrc.d/top`: top part of the file
 * `<dotpath>/vimrc.d/bottom`: bottom part of the file
 
-And you want dotdrop to merge all those files into `~/.vimrc` whenever you process your vimrc with dotdrop.
+And you want dotdrop to merge all those files into `~/.vimrc` whenever you process your .vimrc with dotdrop.
 
-First make sure `~/.vimrc` is present in your config file
+First make sure `~/.vimrc` is present in your config file:
 ```yaml
 ...
 dotfiles:
@@ -49,7 +49,7 @@ Dotdrop will then automagically include the files into your vimrc when handling
 
 To include all files in a directory, a combination of
 [dynvariables](../config-details.md#entry-dynvariables)
-and [jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
+and [Jinja2 directives](https://jinja.palletsprojects.com/en/2.11.x/) have to be used.
 
 Let's say all files in `<dotpath>/toinclude` need to be included into a dotfile.
 
@@ -61,9 +61,9 @@ dynvariables:
 ```
 
 Note that `_dotdrop_dotpath` is part of the built-in variables
-(for more see [template variables](../templating.md#template-variables)).
+(For more, see [template variables](../templating.md#template-variables)).
 
-And then use the generated list in the dotfile template:
+Then use the generated list in the dotfile template:
 ```
 {%@@ for f in allfiles.split() @@%}
   {%@@ include f @@%}
diff --git a/docs/howto/prompt-user-for-variables.md b/docs/howto/prompt-user-for-variables.md
index 0b7e109..06798f5 100644
--- a/docs/howto/prompt-user-for-variables.md
+++ b/docs/howto/prompt-user-for-variables.md
@@ -8,7 +8,7 @@ The provided values are then automatically saved by dotdrop to `uservariables.ya
 which can be included in the main config as a file from which variables are imported
 using [import_variables](../config-details.md#entry-import_variables).
 
-Let's say for example that you want to provide manually the email value
+Let's say, for example, that you want to manually provide the email value
 on new hosts you deploy your dotfiles to.
 
 You'd add the following elements to your config:
diff --git a/docs/howto/sensitive-dotfiles.md b/docs/howto/sensitive-dotfiles.md
index a4e03f0..05c965b 100644
--- a/docs/howto/sensitive-dotfiles.md
+++ b/docs/howto/sensitive-dotfiles.md
@@ -19,33 +19,33 @@ trans_read:
   _gpg: gpg2 -q --for-your-eyes-only --no-tty -d {0} > {1}
 ```
 
-The above config allows to store the dotfile `~/.secret` encrypted in the *dotpath*
+The above config allows you to store the dotfile `~/.secret` encrypted in the *dotpath*
 directory and uses gpg to decrypt it when `install` is run.
 
-Here's how to deploy above solution:
+Here's how to deploy the above solution:
 
-* import the clear dotfile (what creates the correct entries in the config file)
+* Import the clear dotfile (what creates the correct entries in the config file):
 
 ```bash
 $ dotdrop import ~/.secret
 ```
 
-* encrypt the original dotfile
+* Encrypt the original dotfile:
 
 ```bash
 $ <some-gpg-command> ~/.secret
 ```
 
-* overwrite the dotfile with the encrypted version
+* Overwrite the dotfile with the encrypted version:
 
 ```bash
 $ cp <encrypted-version-of-secret> dotfiles/secret
 ```
 
-* edit the config file and add the transformation to the dotfile
+* Edit the config file and add the transformation to the dotfile
   (as shown in the example above)
 
-* commit and push the changes
+* Commit and push the changes
 
 See [transformations](../config-details.md#entry-transformations).
 
@@ -59,7 +59,7 @@ trans_read:
   _gpg: "gpg2 --batch --yes --passphrase-file <({{@@ gpg_password @@}}) -q --for-your-eyes-only --no-tty -d {0} > {1}"
 ```
 
-Passphrase is stored in a file directly
+Passphrase is stored in a file directly:
 ```yaml
 variables:
   gpg_password_file: "/tmp/the-password"
diff --git a/docs/howto/sharing-content.md b/docs/howto/sharing-content.md
index ba4d805..bbfcb75 100644
--- a/docs/howto/sharing-content.md
+++ b/docs/howto/sharing-content.md
@@ -3,9 +3,9 @@
 There are cases in which two or more dotfiles are very similar. For example,
 two files exporting environment variables for two projects built with the same
 technology (eg. two node.js web servers deployed on AWS). In these cases it's
-nice to share as much code as possible across the dotfiles, by leveraging
-templating and merging them in the same dotfile in Dotdrop's `dotpath`. Here
-are a few suggestions about how to achieve this.
+nice to share as much code as possible across the dotfiles by leveraging
+templating and merging them into the same dotfile in dotdrop's `dotpath`. Here
+are a few suggestions about how to achieve this:
 
 * [Brute force templating](#brute-force-templating)
 * [Profile variables](#profile-variables)
@@ -13,7 +13,7 @@ are a few suggestions about how to achieve this.
 
 ## Brute force templating
 
-The first approach is sheer use of templating and variables
+The first approach is sheer use of templating and variables.
 In order to do this, we need to:
 
 1. Create the merged dotfile with an arbitrary name somewhere in `dotpath`.
@@ -38,7 +38,7 @@ export DB_HOST='{{@@ aws_db_host @@}}'
 export DB_PORT='{{@@ aws_db_port @@}}'
 ```
 
-Part of Dotdrop `config.yaml` file:
+Part of dotdrop `config.yaml` file:
 ```yaml
 # config.yaml
 
@@ -63,9 +63,9 @@ export DB_PORT='4521'
 
 ## Profile variables
 
-Albeit flexible, the previous method is a bit cumbersome for some use cases.
+The previous method, albeit flexible, is a bit cumbersome for some use cases.
 For example, when the dotfiles belong to different profiles, the cleanest
-solution consists in using
+solution consists of using
 [profile variables](../config-details.md#entry-profile-variables). This is achieved by:
 
 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
@@ -79,7 +79,7 @@ solution consists in using
 
 An example:
 
-The merged dotfile (`dotpath/projects/env`)
+The merged dotfile (`dotpath/projects/env`):
 ```bash
 # .env
 
@@ -87,7 +87,7 @@ export DB_HOST='{{@@ aws_db_host @@}}'
 export DB_PORT='{{@@ aws_db_port @@}}'
 ```
 
-Part of Dotdrop `config.yaml` file:
+Part of dotdrop `config.yaml` file:
 ```yaml
 # config.yaml
 
@@ -128,26 +128,26 @@ export DB_PORT='9632'
 
 Even though it has cleaner dotfiles, the profile-variable-based procedure can't
 be used in two scenarios: when the dotfiles belong to the same profile, and
-when variable values require some complex computations. In both cases the brute
+when variable values require some complex computations. In both cases, the brute
 force templating approach can be used, but in the latter one it also makes the
 dotfiles bloated with "bookkeeping" logic, thus hard to read.
 
 A solution for this relies in leveraging Jinja macros. This method is a
-variation of the brute force templating one, where the merged dotfile is
-included from many different dotfiles in `dotpath` via jinja macros, rather
+variation of the brute force templating one where the merged dotfile is
+included from many different dotfiles in `dotpath` via Jinja macros rather
 than via many `dotfile` entries with the same `src` attribute. This way, the
-merged original dotfiles stays clean as in the profile variables solution,
+merged original dotfiles stays clean as in the profile variables solution
 because computations are in other files.
 
 The steps to achieve this are:
 
 1. Creating the merged dotfile with an arbitrary name somewhere in `dotpath`.
-2. Wrapping the whole content of the merged dotfile in a jinja macro, with the
+2. Wrapping the whole content of the merged dotfile in a Jinja macro with the
     necessary parameters.
-3. Calling the macro in each original dotfiles, computing the parameters there.
+3. Calling the macro in each original dotfile, computing the parameters there.
 
-**NOTE**: The merged dotfile will be empty, as it only contains a jinja macro.
-    If it needs not to be deployed, the `ignoreempty` entry can be set to
+**NOTE**: The merged dotfile will be empty, as it only contains a Jinja macro.
+    If it needs to not be deployed, the `ignoreempty` entry can be set to
     `true` in `config.yaml`.
 
 As usual, an example:
@@ -162,7 +162,7 @@ export DB_PORT='{{@@ db_port @@}}'
 {%@@ endmacro @@%}
 ```
 
-Server0's environment file (`projects/server0/.env`)
+Server0's environment file (`projects/server0/.env`):
 ```jinja2
 {%@@ from projects/env import env @@%}
 
@@ -182,14 +182,14 @@ Server0's environment file (`projects/server0/.env`)
 {{@@ env(db_host, db_port) @@}}
 ```
 
-Server1's environment file (`projects/server1/.env`)
+Server1's environment file (`projects/server1/.env`):
 ```jinja2
 {%@@ from projects/env import env @@%}
 
 {{@@ env('average-host.com', 9632) @@}}
 ```
 
-Part of Dotdrop `config.yaml` file:
+Part of dotdrop `config.yaml` file:
 ```yaml
 # config.yaml
 
@@ -203,7 +203,6 @@ dotfiles:
   server1-env:
     src: projects/server1/.env
     dst: ~/projects/server1/.env
-
 ```
 
 With this configuration, installing the dotfile `server0-env-local-dbg` will
diff --git a/docs/howto/special-chars.md b/docs/howto/special-chars.md
index c868131..58d230b 100644
--- a/docs/howto/special-chars.md
+++ b/docs/howto/special-chars.md
@@ -8,8 +8,8 @@
 
 ## Detect encoding
 
-Text file encoding can be identified using for example `file -b <file-path>` or in vim
-with `:set fileencoding`
+Text file encoding can be identified using, for example, `file -b <file-path>` or in vim
+with `:set fileencoding`.
 
 Here's an example of encoding that will fully work with dotdrop:
 ```bash
@@ -27,19 +27,20 @@ ISO-8859 text, with escape sequences
 
 ### CRLF
 
-The use of dotfiles with DOS/Windows line ending (CRLF, `\r\n`) will result in
-the comparison (`compare`) returning a difference while there is none.
+The use of dotfiles with DOS/Windows line endings (CRLF, `\r\n`) will result in
+the comparison (`compare`) returning a difference where there is none.
 This is due to Jinja2 stripping CRLF.
 
-One solution is to use `dos2unix` to re-format the dotfiles before adding them                                                       to dotdrop.
+One solution is to use `dos2unix` to re-format the dotfiles before adding them
+to dotdrop.
 
 See <https://github.com/deadc0de6/dotdrop/issues/42>.
 
-### Non-unicode chars
+### Non-Unicode chars
 
-Jinja2 is not able to process non-unicode chars (<https://jinja.palletsprojects.com/en/2.11.x/api/>). This means that dotfiles using non-unicode chars can still be fully managed by dotdrop however when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none.
+Jinja2 is not able to process non-Unicode chars (<https://jinja.palletsprojects.com/en/2.11.x/api/>). This means that dotfiles using non-Unicode chars can still be fully managed by dotdrop; however, when comparing the local file with the one stored in dotdrop, `compare` will return a difference even if there is none.
 
-Either replace the non-unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none.
+Either replace the non-Unicode chars (see below [Re-encode](#re-encode)) or accept the fact the comparison shows a difference while there's none.
 
 See <https://github.com/deadc0de6/dotdrop/issues/42>.
 
diff --git a/docs/howto/store-compressed-directories.md b/docs/howto/store-compressed-directories.md
index 7167b4a..0cc539f 100644
--- a/docs/howto/store-compressed-directories.md
+++ b/docs/howto/store-compressed-directories.md
@@ -1,6 +1,6 @@
 # Handle compressed directories
 
-This is an example on how to use transformations (`trans_read` and `trans_write`) to store
+This is an example of how to use transformations (`trans_read` and `trans_write`) to store
 compressed directories and deploy them with dotdrop.
 
 Config file:
@@ -25,12 +25,12 @@ profiles:
     - d_somedir
 ```
 
-The *read* transformation `uncompress` is used to execute below command before deploying the dotfile (where `{0}` is the source and `{1}` the destination)
+The *read* transformation `uncompress` is used to execute the below command before deploying the dotfile (where `{0}` is the source and `{1}` the destination):
 ```
 mkdir -p {1} && tar -xf {0} -C {1}
 ```
 
-And the *write* transformation `compress` is run when updating the dotfile directory by compressing it (where `{0}` is the source and `{1}` the destination)
+And the *write* transformation `compress` is run when updating the dotfile directory by compressing it (where `{0}` is the source and `{1}` the destination):
 ```
 tar -cf {1} -C {0} .
-```
\ No newline at end of file
+```
diff --git a/docs/howto/symlink-dotfiles.md b/docs/howto/symlink-dotfiles.md
index bf12068..bbc2f3b 100644
--- a/docs/howto/symlink-dotfiles.md
+++ b/docs/howto/symlink-dotfiles.md
@@ -1,34 +1,34 @@
 # Symlink dotfiles
 
 Dotdrop offers two ways to symlink a dotfile through its
-config entry `link`
+config entry `link`:
 
-* setting `link: link` for a dotfile will symlink `dst` to `src`
-* setting `link: link_children` will, for every direct children of `src`, symlink `dst/<childrenX>` to `src/<childrenX>` (see [Link children](#link-children))
+* Setting `link: link` for a dotfile will symlink `dst` to `src`
+* Setting `link: link_children` will, for every direct child of `src`, symlink `dst/<childrenX>` to `src/<childrenX>` (See [Link children](#link-children))
 
-Where `src` is considered as the file stored in your *dotpath* and
-`dst` as the file located in your `$HOME`.
+where `src` is the file stored in your *dotpath* and
+`dst` is the file located in your `$HOME`.
 
-Note that if the dotfile is using template directives, it will be symlinked into
+Note that if the dotfile uses template directives, it will be symlinked into
 `~/.config/dotdrop` instead of directly into your *dotpath*
 (see [Templating symlinked dotfiles](#templating-symlinked-dotfiles))
 
 Although the config entries `link_on_import` and `link_dotfile_default` can be set to the value `link_children`,
-it is not recommended since operations on a dotfile that is not a directory with the option `link_children`
+it is not recommended, since operations on a dotfile that is not a directory with the option `link_children`
 will fail.
 
 ## Symlink a dotfile
 
-Below is the ad-hoc way when [link_dotfile_default](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry)
+Below is an ad-hoc way to symlink a dotfile when [link_dotfile_default](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry)
 and [link_on_import](https://dotdrop.readthedocs.io/en/latest/config-format/#config-entry) use their default values.
 
-import the file
+Import the file:
 ```bash
 $ ./dotdrop.sh import ~/.bashrc
 	-> "/home/user/.bashrc" imported
 ```
 
-edit the `config.yaml` and set the `link` value to `link`
+Edit the `config.yaml` and set the `link` value to `link`:
 ```yaml
 dotfiles:
   f_bashrc:
@@ -37,7 +37,7 @@ dotfiles:
     link: link
 ```
 
-install the dotfile what will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop
+Install the dotfile, which will remove your `~/.bashrc` and replace it with a link to the file stored in dotdrop:
 ```bash
 $ ./dotdrop.sh install
 Remove "/home/user/.bashrc" for link creation? [y/N] ? y
@@ -46,7 +46,7 @@ Remove "/home/user/.bashrc" for link creation? [y/N] ? y
 1 dotfile(s) installed.
 ```
 
-The dotfile then points to the file in dotdrop
+The dotfile then points to the file in dotdrop:
 ```bash
 $ readlink ~/.bashrc
 /home/user/dotdrop/dotfiles/bashrc
@@ -55,16 +55,16 @@ $ readlink ~/.bashrc
 ## Link children
 
 The `link_children` option can be very useful for dotfiles when you don't want the entire
-directory to be symlink but still want to keep a clean config files (with a
+directory to be symlinked but still want to keep a clean config file (with a
 limited number of entries).
 
-This option set on a file that is not a directory will make any operation on the dotfile fail.
+Setting this option on a file that is not a directory will make any operation on the dotfile fail.
 
-*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`*
+*Make sure to do a backup of your dotfiles with something like `cp -r <my-important-dotfile>{,.bak}`.*
 
 A good example of its use is when managing `~/.vim` with dotdrop.
 
-Here's what it looks like when using `link: link`.
+Here's what it looks like when using `link: link`:
 ```yaml
 config:
   dotpath: dotfiles
@@ -75,7 +75,7 @@ dotfiles:
     link: link
 ```
 
-The top directory `~/.vim` is symlinked to the `<dotpath>/vim` location
+The top directory `~/.vim` is symlinked to the `<dotpath>/vim` location:
 ```bash
 $ readlink ~/.vim
 ~/.dotfiles/vim/
@@ -84,12 +84,12 @@ after  autoload  plugged  plugin  snippets  spell  swap  vimrc
 ```
 
 As a result, all files under `~/.vim` will be managed by
-dotdrop (including unwanted directories like `spell`, `swap`, etc).
+dotdrop (including unwanted directories like `spell`, `swap`, etc.).
 
-A cleaner solution is to use `link_children` which allows to only symlink
+A cleaner solution is to use `link_children` which allows you to only symlink
 files under the dotfile directory. Let's say only `after`, `plugin`, `snippets`, and `vimrc`
-need to be managed in dotdrop. `~/.vim` is imported in dotdrop, cleaned off all unwanted
-files/directories and then the `link` entry is set to `link_children` in the config file.
+need to be managed in dotdrop. `~/.vim` is imported in dotdrop and cleaned of all unwanted
+files/directories, and then the `link` entry is set to `link_children` in the config file:
 ```yaml
 config:
   dotpath: dotfiles
@@ -120,15 +120,15 @@ $ tree -L 1 ~/.vim
 
 ## Templating symlinked dotfiles
 
-For dotfiles not using any templating directives, those are directly linked
+Dotfiles not using any templating directives are directly linked
 to dotdrop's `dotpath` directory (see [Config](../config.md)).
 
-When using templating directives however the dotfiles are first installed into
-`workdir` (defaults to *~/.config/dotdrop*, see [Config](../config.md))
+When using templating directives, however, the dotfiles are first installed into
+`workdir` (defaults to *~/.config/dotdrop*; see [Config format](../config-format.md))
 and then symlinked there.
 This applies to both dotfiles with `link: link` and `link: link_children`.
 
-For example
+For example:
 ```bash
 # with template
 /home/user/.xyz -> /home/user/.config/dotdrop/.xyz
diff --git a/docs/howto/system-config-files.md b/docs/howto/system-config-files.md
index 27ed6a9..fa43584 100644
--- a/docs/howto/system-config-files.md
+++ b/docs/howto/system-config-files.md
@@ -1,18 +1,18 @@
 # Manage system dotfiles
 
-Dotdrop doesn't allow to handle file owernership (at least not directly). Every file operations (create/copy file/directory, create symlinks, etc) are executed with the rights of the user calling dotdrop.
+Dotdrop doesn't allow you to handle file owernership (at least not directly). Every file operation (create/copy file/directory, create symlinks, etc.) is executed with the rights of the user calling dotdrop.
 
-Using dotdrop with `sudo` to unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed up owners.
+Using dotdrop with `sudo` to manage unprivileged and privileged files in the same *session* is a bad idea as the resulting files will all have messed-up owners.
 
-It is therefore recommended to have two different config files (and thus two different *dotpath*)
+It is therefore recommended to have two different config files (and thus two different *dotpath*s)
 for handling these two uses cases:
 
 For example:
 
-* one `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`)
-* one `config-root.yaml` for the system/root dotfiles (with its dedicated *dotpath*, for example `dotfiles-root`)
+* One `config-user.yaml` for the local/user dotfiles (with its dedicated *dotpath*, for example `dotfiles-user`)
+* One `config-root.yaml` for the system/root dotfiles (with its dedicated *dotpath*, for example `dotfiles-root`)
 
-`config-user.yaml` is used when managing the user's dotfiles
+`config-user.yaml` is used when managing the user's dotfiles:
 ```bash
 ## user config file is config-user.yaml
 $ ./dotdrop.sh import --cfg config-user.yaml <some-dotfile>
@@ -20,7 +20,7 @@ $ ./dotdrop.sh install --cfg config-user.yaml
 ...
 ```
 
-`config-root.yaml` is used when managing system's dotfiles and is to be used with `sudo` or directly by the root user
+`config-root.yaml` is used when managing the system's dotfiles and is to be used with `sudo` or directly by the root user:
 ```bash
 ## root config file is config-root.yaml
 $ sudo ./dotdrop.sh import --cfg=config-root.yaml <some-dotfile>
diff --git a/docs/installation.md b/docs/installation.md
index 83d25e6..99fabdf 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -2,14 +2,14 @@
 
 Installing dotdrop [as a submodule](#as-a-submodule) is the recommended way.
 
-If you want to keep your python environment clean, use the virtualenv installation instructions
+If you want to keep your Python environment clean, use the virtualenv installation instructions
 (see [As a submodule in a virtualenv](#as-a-submodule-in-a-virtualenv) and
-[Pypi package in a virtualenv](#pypi-package-in-a-virtualenv)).
+[PyPI package in a virtualenv](#pypi-package-in-a-virtualenv)).
 In that case, the virtualenv environment might need to be loaded before any attempt to use dotdrop.
 
 ## As a submodule
 
-The following will create a git repository for your dotfiles and
+The following will create a Git repository for your dotfiles and
 keep dotdrop as a submodule:
 ```bash
 ## create the repository
@@ -25,15 +25,15 @@ $ ./dotdrop/bootstrap.sh
 $ ./dotdrop.sh --help
 ```
 
-For MacOS users, make sure to install `realpath` through homebrew
+For macOS users, make sure to install `realpath` through Homebrew
 (part of *coreutils*).
 
-Using this solution will need you to work with dotdrop by
+Using this solution will require you to work with dotdrop by
 using the generated script `dotdrop.sh` at the root
 of your dotfiles repository.
 
 To ease the use of dotdrop, it is recommended to add an alias to it in your
-shell with the config file path, for example
+shell with the config file path; for example:
 ```
 alias dotdrop=<absolute-path-to-dotdrop.sh> --cfg=<path-to-your-config.yaml>'
 ```
@@ -58,7 +58,7 @@ $ ./dotdrop/bootstrap.sh
 $ ./dotdrop.sh --help
 ```
 
-When using a virtualenv, make sure to source the environment before using dotdrop
+When using a virtualenv, make sure to source the environment before using dotdrop:
 ```bash
 $ source env/bin/activate
 $ ./dotdrop.sh --help
@@ -66,18 +66,18 @@ $ ./dotdrop.sh --help
 
 Then follow the instructions under [As a submodule](#as-a-submodule).
 
-## Pypi package
+## PyPI package
 
-Install dotdrop
+Install dotdrop:
 ```bash
 $ pip3 install dotdrop --user
 ```
 
-and then [setup your repository](repository-setup.md).
+and then [set up your repository](repository-setup.md).
 
-## Pypi package in a virtualenv
+## PyPI package in a virtualenv
 
-Install dotdrop in a virtualenv from pypi
+Install dotdrop from PyPI in a virtualenv:
 ```bash
 $ virtualenv -p python3 env
 $ source env/bin/activate
@@ -91,14 +91,14 @@ $ source env/bin/activate
 $ dotdrop --help
 ```
 
-Then follow the instructions under [Pypi package](#pypi-package).
+Then follow the instructions under [PyPI package](#pypi-package).
 
 ## Aur packages
 
 Dotdrop is available on aur:
 
-* stable: <https://aur.archlinux.org/packages/dotdrop/>
-* git version: <https://aur.archlinux.org/packages/dotdrop-git/>
+* Stable: <https://aur.archlinux.org/packages/dotdrop/>
+* Git version: <https://aur.archlinux.org/packages/dotdrop-git/>
 
 Make sure to install the [python-magic-ahupp](https://aur.archlinux.org/packages/python-magic-ahupp/) from aur.
 
@@ -106,16 +106,16 @@ Then follow the [doc to setup your repository](repository-setup.md).
 
 ## Snap package
 
-Dotdrop is available as a snap package: <https://snapcraft.io/dotdrop>
+Dotdrop is available as a snap package: <https://snapcraft.io/dotdrop>.
 
-Install it with
+Install it with:
 ```bash
 snap install dotdrop
 ```
 
 Then follow the [doc to setup your repository](repository-setup.md).
 
-If you encounter warnings like `Warning: using regular magic file`
+If you encounter warnings like `Warning: using regular magic file`,
 try defining the following environment variable:
 ```bash
 export MAGIC=$SNAP/usr/share/file/magic.mgc
@@ -123,7 +123,7 @@ export MAGIC=$SNAP/usr/share/file/magic.mgc
 
 ## From source
 
-Clone the repository
+Clone the repository:
 ```bash
 $ git clone https://github.com/deadc0de6/dotdrop.git
 ```
@@ -138,14 +138,14 @@ $ ./dotdrop.sh --cfg <my-config-file> files
 
 ## Dependencies
 
-Beside the python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
-dotdrop depends on following tools:
+Beside the Python dependencies defined in [requirements.txt](https://github.com/deadc0de6/dotdrop/blob/master/requirements.txt),
+dotdrop depends on the following tools:
 
 * `diff`
 * `git` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
 * `readlink` or `realpath` (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh))
 
-For MacOS users, make sure to install below packages through [homebrew](https://brew.sh/):
+For macOS users, make sure to install the below packages through [Homebrew](https://brew.sh/):
 
 * [coreutils](https://formulae.brew.sh/formula/coreutils) (only if using the entry point script [dotdrop.sh](https://github.com/deadc0de6/dotdrop/blob/master/dotdrop.sh) which uses realpath)
 * [libmagic](https://formulae.brew.sh/formula/libmagic) (for python-magic)
@@ -162,13 +162,13 @@ is auto-updated through the [dotdrop.sh](https://github.com/deadc0de6/dotdrop/bl
 script by defining the environment variable `DOTDROP_AUTOUPDATE=yes`.
 If undefined, `DOTDROP_AUTOUPDATE` will take the value `yes`.
 
-If used as a submodule, update it with
+If used as a submodule, update it with:
 ```bash
 $ git submodule update --init --recursive
 $ git submodule update --remote dotdrop
 ```
 
-You will then need to commit the changes with
+You will then need to commit the changes with:
 ```bash
 $ git add dotdrop
 $ git commit -m 'update dotdrop'
@@ -180,7 +180,7 @@ $ git push
 If you wish to get a specific version of dotdrop when using
 it as a submodule, the following operations can be done.
 
-Here dotdrop is downgraded to the latest stable version
+Here dotdrop is downgraded to the latest stable version:
 ```bash
 ## enter the repository containing the dotdrop submodule
 $ cd my-dotfiles
@@ -197,11 +197,9 @@ automatically update dotdrop back to the latest commit.
 
 ## Shell completion
 
-Completion scripts exist for `bash`, `zsh` and `fish`,
+Completion scripts exist for `bash`, `zsh` and `fish`;
 see [the related doc](https://github.com/deadc0de6/dotdrop/blob/master/completion/README.md).
 
 ## Highlighters
 
 Highlighters for dotdrop templates are available [here](https://github.com/deadc0de6/dotdrop/tree/master/highlighters).
-
-
diff --git a/docs/misc/migrate-from-submodule.md b/docs/misc/migrate-from-submodule.md
index b81b298..d74f32f 100644
--- a/docs/misc/migrate-from-submodule.md
+++ b/docs/misc/migrate-from-submodule.md
@@ -5,10 +5,10 @@ Only do the following if you are using dotdrop version `< 0.7.1` or if you encou
 ---
 
 Initially dotdrop was only available as a submodule directly in the
-dotfiles git tree. When updated to work with pypi, some code changed
+dotfiles git tree. When updated to work with PyPI, some code changed
 that brought some issues to older versions.
 
-If you want to keep it as a submodule (recommended), simply do the following
+If you want to keep it as a submodule (recommended), simply do the following:
 ```bash
 $ cd <dotfiles-directory>
 
@@ -30,40 +30,40 @@ $ git commit -m 'update dotdrop.sh'
 $ git push
 ```
 
-Otherwise, simply install it from pypi as shown below:
+Otherwise, simply install it from PyPI as shown below:
 
-* move to the dotfiles directory where dotdrop is used as a submodule
+* Move to the dotfiles directory where dotdrop is used as a submodule
 ```bash
 $ cd <dotfiles-repository>
 ```
-* remove the entire `submodule "dotdrop"` section in `.gitmodules`
-* stage the changes
+* Remove the entire `submodule "dotdrop"` section in `.gitmodules`
+* Stage the changes
 ```bash
 $ git add .gitmodules
 ```
-* remove the entire `submodule "dotdrop"` section in `.git/config`
-* remove the submodule
+* Remove the entire `submodule "dotdrop"` section in `.git/config`
+* Remove the submodule
 ```bash
 $ git rm --cached dotdrop
 ```
-* remove the submodule from .git
+* Remove the submodule from .git
 ```bash
 $ rm -rf .git/modules/dotdrop
 ```
-* commit the changes
+* Commit the changes
 ```bash
 $ git commit -m 'removing dotdrop submodule'
 ```
-* remove any remaining files from the dotdrop submodule
+* Remove any remaining files from the dotdrop submodule
 ```bash
 $ rm -rf dotdrop
 ```
-* remove `dotdrop.sh`
+* Remove `dotdrop.sh`
 ```bash
 $ git rm dotdrop.sh
 $ git commit -m 'remove dotdrop.sh script'
 ```
-* push upstream
+* Push upstream
 ```bash
 $ git push
 ```
diff --git a/docs/misc/people-using-dotdrop.md b/docs/misc/people-using-dotdrop.md
index 1a72756..1d90c83 100644
--- a/docs/misc/people-using-dotdrop.md
+++ b/docs/misc/people-using-dotdrop.md
@@ -1,4 +1,4 @@
-For more examples, see how people are using dotdrop
+For more examples, see how people are using dotdrop:
 
 * [https://github.com/open-dynaMIX/dotfiles](https://github.com/open-dynaMIX/dotfiles)
 * [https://github.com/moyiz/dotfiles](https://github.com/moyiz/dotfiles)
@@ -7,6 +7,6 @@ For more examples, see how people are using dotdrop
 * [https://github.com/Eluminae/dotfiles](https://github.com/Eluminae/dotfiles)
 * [https://github.com/davla/dotfiles](https://github.com/davla/dotfiles) and [https://github.com/davla/setup](https://github.com/davla/setup)
 
-Dotfiles repository using dotdrop on [github](https://github.com/topics/dotdrop?o=desc&s=updated) and [gitlab](https://gitlab.com/search?search=dotdrop).
+Dotfiles repositories using dotdrop on [GitHub](https://github.com/topics/dotdrop?o=desc&s=updated) and [GitLab](https://gitlab.com/search?search=dotdrop).
 
-Or search directly on [github](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code) for config examples.
+Or search directly on [GitHub](https://github.com/search?q=filename%3Aconfig.yaml+dotdrop&type=Code) for config examples.
diff --git a/docs/repository-setup.md b/docs/repository-setup.md
index 08d5abd..c6e18ee 100644
--- a/docs/repository-setup.md
+++ b/docs/repository-setup.md
@@ -1,6 +1,6 @@
 # Repository setup
 
-Either create a git repository on your prefered platform and clone it or create one locally.
+Either create a Git repository on your prefered platform and clone it or create one locally.
 This repository will contain two main elements, dotdrop's config file (`config.yaml`)
 and a directory containing all your dotfiles managed by dotdrop.
 ```bash
@@ -15,12 +15,12 @@ $ mkdir dotfiles
 
 Then add a config file. You can get a
 [minimal config file](https://github.com/deadc0de6/dotdrop/blob/master/config.yaml)
-from dotdrop's repository with
+from dotdrop's repository with:
 ```bash
 $ wget https://raw.githubusercontent.com/deadc0de6/dotdrop/master/config.yaml
 ```
 It is recommended to store your config file directly within your repository
-(*my-dotfiles* in the example above) but you could save it in different places if you wish,
+(*my-dotfiles* in the example above), but you could save it in different places if you wish;
 see [config location](config.md#location) for more.
 
 ```bash
diff --git a/docs/templating.md b/docs/templating.md
index 18de338..5450218 100644
--- a/docs/templating.md
+++ b/docs/templating.md
@@ -1,49 +1,49 @@
 # Templating
 
-Dotdrop leverage the power of [jinja2](https://palletsprojects.com/p/jinja/) to handle the
-templating of dotfiles. See [jinja2 template doc](https://jinja.palletsprojects.com/en/2.11.x/templates/)
+Dotdrop leverages the power of [Jinja2](https://palletsprojects.com/p/jinja/) to handle the
+templating of dotfiles. See [the Jinja2 templates docs](https://jinja.palletsprojects.com/en/2.11.x/templates/)
 or the below sections for more information on how to template your dotfiles.
 
 ## Templating or not templating
 
 The dotfile config entry [template](config-format.md#dotfiles-entry)
 and the global config entry [template_dotfile_default](config-format.md#config-entry)
-allow to control if a dotfile is being process by the templating engine.
+allow you to control whether a dotfile is processed by the templating engine.
 
-Obviously if the dotfile uses template directives, it needs to be templated. However if it
+Obviously, if the dotfile uses template directives, it needs to be templated. However, if it
 is not, disabling templating will speed up its installation (since it won't have to be
 processed by the engine).
 
 For dotfiles being symlinked (`link` or `link_children`), see
-[the dedicated doc](howto/symlink-dotfiles.md#templating-symlinked-dotfiles)
+[the dedicated doc](howto/symlink-dotfiles.md#templating-symlinked-dotfiles).
 
 ## Delimiters
 
 Dotdrop uses different delimiters than
-[jinja2](https://palletsprojects.com/p/jinja/)'s defaults:
+[Jinja2](https://palletsprojects.com/p/jinja/)'s defaults:
 
-* block/statement start = `{%@@`
-* block/statement end = `@@%}`
-* variable/expression start = `{{@@`
-* variable/expression end = `@@}}`
-* comment start = `{#@@`
-* comment end = `@@#}`
+* Block/statement start = `{%@@`
+* Block/statement end = `@@%}`
+* Variable/expression start = `{{@@`
+* Variable/expression end = `@@}}`
+* Comment start = `{#@@`
+* Comment end = `@@#}`
 
-More info in [jinja2 templating doc](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
+More info in [Jinja2 templating docs](https://jinja.palletsprojects.com/en/2.11.x/templates/?highlight=delimiter)
 
 ## Template variables
 
-Following variables are available in templates:
+The following variables are available in templates:
 
 * `{{@@ profile @@}}` contains the profile provided to dotdrop.
 * `{{@@ env['MY_VAR'] @@}}` contains environment variables (see [Environment variables](#environment-variables)).
-* `{{@@ header() @@}}` contains dotdrop header (see [Dotdrop header](#dotdrop-header)).
+* `{{@@ header() @@}}` contains the dotdrop header (see [Dotdrop header](#dotdrop-header)).
 * `{{@@ _dotdrop_dotpath @@}}` contains the [dotpath](config-format.md) absolute path.
 * `{{@@ _dotdrop_cfgpath @@}}` contains the absolute path to the [config file](config.md).
 * `{{@@ _dotdrop_workdir @@}}` contains the [workdir](config-format.md) absolute path.
-* dotfile specific variables (see [Dotfile variables](#dotfile-variables))
-* all defined config variables (see [Variables](config.md#variables)).
-* all defined config interpreted variables (see [Interpreted variables](config-details.md#entry-dynvariables)).
+* Dotfile specific variables (see [Dotfile variables](#dotfile-variables))
+* All defined config variables (see [Variables](config.md#variables))
+* All defined config interpreted variables (see [Interpreted variables](config-details.md#dynvariables-entry))
 
 ## Dotfile variables
 
@@ -54,20 +54,20 @@ When a dotfile is handled by dotdrop, the following variables are added:
 * `{{@@ _dotfile_key @@}}` contains the processed dotfile key.
 * `{{@@ _dotfile_link @@}}` contains the processed dotfile `link` string value.
 
-Additionally to the above, the following variables are set in each file processed by dotdrop.
+In addition to the above, the following variables are set in each file processed by dotdrop:
 
 * `{{@@ _dotfile_sub_abs_src @@}}` contains the absolute source path of each file when handled by dotdrop.
 * `{{@@ _dotfile_sub_abs_dst @@}}` contains the absolute destination path of each file when handled by dotdrop.
 
-For example a directory dotfile (like `~/.ssh`) would process several files
+For example, a directory dotfile (like `~/.ssh`) would process several files
+(`~/.ssh/config` and `~/.ssh/authorized_keys`, for example). In `~/.ssh/config`:
 
-(`~/.ssh/config` and `~/.ssh/authorized_keys` for example). In `~/.ssh/config`:
 * `_dotfile_abs_dst` would be `/home/user/.ssh`
 * `_dotfile_sub_abs_dst` would be `/home/user/.ssh/config`
 
 ## Environment variables
 
-It's possible to access environment variables inside the templates.
+It's possible to access environment variables inside the templates:
 ```
 {{@@ env['MY_VAR'] @@}}
 ```
@@ -75,14 +75,14 @@ It's possible to access environment variables inside the templates.
 This allows for storing host-specific properties and/or secrets in environment variables.
 It is recommended to use `variables` (see [config variables](config.md#variables))
 instead of environment variables unless these contain sensitive information that
-shouldn't be versioned in git.
+shouldn't be versioned in Git.
 
-For example you can have a `.env` file in the directory where your `config.yaml` lies:
+For example, you can have an `.env` file in the directory where your `config.yaml` lies:
 ```
 ## Some secrets
 pass="verysecurepassword"
 ```
-If this file contains secrets that should not be tracked by git,
+If this file contains secrets that should not be tracked by Git,
 put it in your `.gitignore`.
 
 You can then invoke dotdrop with the help of an alias
@@ -99,30 +99,30 @@ The above aliases load all the variables from `~/dotfiles/.env`
 
 ## Template methods
 
-Beside [jinja2 global functions](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-global-functions)
-the following methods can be used within the templates:
+Besides [Jinja2 global functions](https://jinja.palletsprojects.com/en/2.11.x/templates/#list-of-global-functions),
+the following methods can be used within templates:
 
-* `exists(path)`: return true when path exists
+* `exists(path)`: returns true when path exists
 ```
 {%@@ if exists('/dev/null') @@%}
 it does exist
 {%@@ endif @@%}
 ```
 
-* `exists_in_path(name, path=None)`: return true when executable exists in `$PATH`
+* `exists_in_path(name, path=None)`: returns true when executable exists in `$PATH`
 ```
 {%@@ if exists_in_path('exa') @@%}
 alias ls='exa --git --color=always'
 {%@@ endif @@%}
 ```
 
-* `basename(path)`: return the `basename` of the path argument
+* `basename(path)`: returns the `basename` of the path argument
 ```
 {%@@ set dotfile_filename = basename( _dotfile_abs_dst ) @@%}
 dotfile dst filename: {{@@ dotfile_filename @@}}
 ```
 
-* `dirname(path)`: return the `dirname` of the path argument
+* `dirname(path)`: returns the `dirname` of the path argument
 ```
 {%@@ set dotfile_dirname = dirname( _dotfile_abs_dst ) @@%}
 dotfile dst dirname: {{@@ dotfile_dirname @@}}
@@ -133,20 +133,20 @@ config entry `func_file`.
 
 Example:
 
-the config file
+The config file:
 ```yaml
 config:
   func_file:
   - /tmp/myfuncs_file.py
 ```
 
-the python function under `/tmp/myfuncs_file.py`
+The python function under `/tmp/myfuncs_file.py`:
 ```python
 def myfunc(arg):
   return not arg
 ```
 
-the dotfile content
+The dotfile content:
 ```
 {%@@ if myfunc(False) @@%}
 this should exist
@@ -155,44 +155,44 @@ this should exist
 
 ## Template filters
 
-Beside [jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters)
+Besides [Jinja2 builtin filters](https://jinja.palletsprojects.com/en/2.11.x/templates/#builtin-filters),
 custom user-defined filter functions can be loaded using the config entry `filter_file`:
 
 Example:
 
-the config file
+The config file:
 ```yaml
 config:
   filter_file:
   - /tmp/myfilter_file.py
 ```
 
-the python filter under `/tmp/myfilter_file.py`
+The python filter under `/tmp/myfilter_file.py`:
 ```python
 def myfilter(arg1):
   return str(int(arg1) - 10)
 ```
 
-the dotfile content
+The dotfile content:
 ```
 {{@@ "13" | myfilter() @@}}
 ```
 
 For more information on how to create filters,
-see [jinja2 official doc](https://jinja.palletsprojects.com/en/2.11.x/api/#writing-filters).
+see [the Jinja2 official docs](https://jinja.palletsprojects.com/en/2.11.x/api/#writing-filters).
 
-## Import macros
+## Importing macros
 
 Macros must be imported `with context` in order to have access to the variables:
 ```
 {%@@ from 'macro_file' import macro with context @@%}
 ```
 
-For more see the [dedicated jinja2 doc](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
+For more information, see the [dedicated Jinja2 docs](https://jinja.palletsprojects.com/en/2.11.x/templates/#macros).
 
 ## Dotdrop header
 
-Dotdrop is able to insert a header in the generated dotfiles. This allows
+Dotdrop is able to insert a header in the generated dotfiles. This allows you
 to remind anyone opening the file for editing that this file is managed by dotdrop.
 
 Here's what it looks like:
@@ -205,13 +205,13 @@ The header can be automatically added with:
 {{@@ header() @@}}
 ```
 
-Properly commenting the header in templates is the responsibility of the user
-as [jinja2](https://palletsprojects.com/p/jinja/) has no way of knowing what is the proper char(s) used for comments.
+Properly commenting the header in templates is the responsibility of the user,
+as [Jinja2](https://palletsprojects.com/p/jinja/) has no way of knowing what is the proper char(s) used for comments.
 Either prepend the directive with the commenting char(s) used in the dotfile
 (for example `# {{@@ header() @@}}`) or provide it as an argument `{{@@ header('# ') @@}}`.
-The result is equivalent.
+The results are equivalent.
 
-## Debug templates
+## Debugging templates
 
 To debug the result of a template, one can install the dotfiles to a temporary
 directory with the `install` command and the `-t` switch:
diff --git a/docs/usage.md b/docs/usage.md
index 8145428..68e4dd0 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -4,18 +4,18 @@ Run `dotdrop --help` to see all available options.
 
 ## Basic usage
 
-The basic use of dotdrop is
+The basic use of dotdrop is:
 
-* import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
-* install the dotfiles (will *copy/link* those from your `dotpath` to the filesystem): `dotdrop install`
+* Import a file/directory to manage (this will copy the files from the filesystem to your `dotpath`): `dotdrop import <somefile>`
+* Install the dotfiles (this will *copy/link* them from your `dotpath` to the filesystem): `dotdrop install`
 
-Then if you happen to update the file/directory directly on the filesystem (add new file/dir, edit content, etc) you can use the `update` command to mirror back those changes in dotdrop.
+Then if you happen to update the file/directory directly on the filesystem (add a new file/dir, edit content, etc.) you can use the `update` command to mirror back those changes in dotdrop.
 
 For more advanced uses:
 
-* `dotdrop --help` for the cli usage.
-* [the example](https://github.com/deadc0de6/dotdrop#getting-started)
-* [the howto](howto/howto.md)
+* `dotdrop --help` for the CLI usage.
+* [The example](https://github.com/deadc0de6/dotdrop#getting-started)
+* [The howto](howto/howto.md)
 
 ## Profile
 
@@ -23,17 +23,17 @@ The default profile used by dotdrop is the *hostname* of the host you are runnin
 
 It can be changed:
 
-* using the command line switch `-p --profile=<profile>`
-* by defining it in the env variable `DOTDROP_PROFILE`
+* Using the command line switch `-p`/`--profile=<profile>`
+* By defining it in the env variable `DOTDROP_PROFILE`
 
 ## Import dotfiles
 
 The `import` command imports dotfiles to be managed by dotdrop.
 It copies the dotfile to your `dotpath` and updates the config file with the new entry.
 
-Dotdrop will ask for dereferencing symlinks on import unless `-f --force` is used.
+Dotdrop will ask whether to dereference symlinks on import unless `-f`/`--force` is used.
 
-For example to import `~/.xinitrc`
+For example, to import `~/.xinitrc`:
 ```bash
 $ dotdrop import ~/.xinitrc
 	-> "/home/user/.xinitrc" imported
@@ -42,35 +42,35 @@ $ dotdrop import ~/.xinitrc
 ```
 
 You can control how the dotfile key is generated in the config file
-with the config entry `longkey` (per default to *false*).
+with the config entry `longkey` (defaults to *false*).
 
 Two formats are available:
 
 * *short format* (default): take the shortest unique path
 * *long format*: take the full path
 
-For example `~/.config/awesome/rc.lua` gives
+For example, `~/.config/awesome/rc.lua` gives:
 
 * `f_rc.lua` in the short format
 * `f_config_awesome_rc.lua` in the long format
 
-Importing `~/.mutt/colors` and then `~/.vim/colors` will result in
+Importing `~/.mutt/colors` and then `~/.vim/colors` will result in:
 
 * `d_colors` and `d_vim_colors` in the short format
 * `d_mutt_colors` and `d_vim_colors` in the long format
 
-Dotfiles can be imported as a different file with the use
+A dotfile can be imported as a different file with the use
 of the command line switch `--as` (effectively selecting the `src` part
 of the dotfile in the config). It is however recommended
 to use [templating](templating.md) to avoid duplicates and optimize
-dotfiles management.
+dotfile management.
 ```bash
 $ dotdrop import ~/.zshrc --as=~/.zshrc.test
 ```
 
-To ignore specific pattern during import see [the ignore patterns](config.md#ignore-patterns)
+To ignore specific patterns during import, see [the ignore patterns](config.md#ignore-patterns).
 
-For more options, see the usage with `dotdrop --help`
+For more options, see the usage with `dotdrop --help`.
 
 ## Install dotfiles
 
@@ -79,49 +79,45 @@ The `install` command installs/deploys dotfiles managed by dotdrop from the `dot
 $ dotdrop install
 ```
 
-The dotfile will be installed only if it differs from the version already present on its destination.
+A dotfile will be installed only if it differs from the version already present at its destination.
 
-some available options
+Some available options:
 
-* `-t --temp`: install the dotfile(s) to a temporary directory for review (it helps to debug templating issues for example).
-  Note that actions are not executed in that mode.
-* `-a --force-actions`: force the execution of actions even if the dotfiles are not installed
-* `-f --force`: do not ask any confirmation
+* `-t`/`--temp`: Install the dotfile(s) to a temporary directory for review (helping to debug templating issues, for example).
+  Note that actions are not executed in this mode.
+* `-a`/`--force-actions`: Force the execution of actions even if the dotfiles are not installed
+* `-f`/`--force`: Do not ask for any confirmation
 
-To ignore specific pattern during installation see [the ignore patterns](config.md#ignore-patterns)
+To ignore specific patterns during installation, see [the ignore patterns](config.md#ignore-patterns).
 
-For more options, see the usage with `dotdrop --help`
+For more options, see the usage with `dotdrop --help`.
 
 ## Compare dotfiles
 
-The `compare` command compares dotfiles on their destination with the one stored in your `dotpath`.
+The `compare` command compares dotfiles at their destinations with the ones stored in your `dotpath`.
 ```bash
 $ dotdrop compare
 ```
 
-The diffing is done by the unix tool `diff` in the backend, one can provide its specific
+The diffing is done with the UNIX tool `diff` as the backend; one can provide a specific
 diff command using the config entry `diff_command`.
 
-To ignore specific pattern, see [the ignore patterns](config.md#ignore-patterns)
+To ignore specific patterns, see [the ignore patterns](config.md#ignore-patterns).
 
-To completely ignore all files not present in `dotpath` see [ignore missing](#ignore-missing).
-
-It is also possible to install all dotfiles for a specific profile
-in a temporary directory in order to manually compare them with
-the local version by using `install` and the `-t` switch.
+To completely ignore all files not present in `dotpath` see [Ignore missing](#ignore-missing).
 
 For more options, see the usage with `dotdrop --help`.
 
 ## List profiles
 
-The `profiles` command lists defined profiles in the config file
+The `profiles` command lists the profiles defined in the config file.
 ```bash
 $ dotdrop profiles
 ```
 
-Dotdrop allows to choose which profile to use
+Dotdrop allows you to choose which profile to use
 with the `--profile` switch if you use something
-else than the default (the hostname).
+other than the default (the hostname).
 
 The default profile can also be changed by defining the
 `DOTDROP_PROFILE` environment variable.
@@ -137,10 +133,10 @@ f_xinitrc
 	-> link: nolink
 ```
 
-By using the `-T --template` switch, only the dotfiles that
+By using the `-T`/`--template` switch, only the dotfiles that
 are using [templating](templating.md) are listed.
 
-It is also possible to list all files related to each dotfile entries
+It is also possible to list all the files related to each dotfile entry
 by invoking the `detail` command, for example:
 ```bash
 $ dotdrop detail
@@ -151,19 +147,19 @@ f_xinitrc (dst: "/home/user/.xinitrc", link: nolink)
 
 This is especially useful when the dotfile entry is a directory
 and one wants to have information on the different files it contains
-(does a specific file uses templating, etc).
+(does a specific file uses templating, etc.).
 
-For more options, see the usage with `dotdrop --help`
+For more options, see the usage with `dotdrop --help`.
 
 ## Update dotfiles
 
-The `update` commands will updates a dotfile managed by dotdrop by copying the dotfile
+The `update` command updates a dotfile managed by dotdrop by copying the dotfile
 from the filesystem to the `dotpath`. Only dotfiles that have differences with the stored version are updated.
-A confirmation is requested from the user before any overwrite/update unless the `-f --force` switch is used.
+A confirmation is requested from the user before any overwrite/update unless the `-f`/`--force` switch is used.
 
 Either provide the path of the file containing the new version of the dotfile or
-provide the dotfile key to update (as found in the config file) along with the `-k --key` switch.
-When using the `-k --key` switch and no key is provided, all dotfiles for that profile are updated.
+provide the dotfile key to update (as found in the config file) along with the `-k`/`--key` switch.
+When using the `-k`/`--key` switch and no key is provided, all dotfiles for that profile are updated.
 ```bash
 ## update by path
 $ dotdrop update ~/.vimrc
@@ -174,16 +170,16 @@ $ dotdrop update --key f_vimrc
 
 If not argument is provided, all dotfiles for the selected profile are updated.
 
-To ignore specific pattern, see [the dedicated page](config.md#ignore-patterns)
+To ignore specific patterns, see [the dedicated page](config.md#ignore-patterns).
 
-To completely ignore all files not present in `dotpath` see [ignore missing](#ignore-missing).
+To completely ignore all files not present in `dotpath`, see [Ignore missing](#ignore-missing).
 
 There are two cases when updating a dotfile:
 
 ### The dotfile doesn't use [templating](templating.md)
 
 The new version of the dotfile is copied to the *dotpath* directory and overwrites
-the old version. If git is used to version the dotfiles stored by dotdrop, the git command
+the old version. If Git is used to version the dotfiles stored by dotdrop, the Git command
 `diff` can be used to view the changes.
 
 ```bash
@@ -193,18 +189,18 @@ $ git diff
 
 ### The dotfile uses [templating](templating.md)
 
-The dotfile must be manually updated, three solutions can be used to identify the
+The dotfile must be manually updated; three solutions can be used to identify the
 changes to apply to the template:
 
-* Use the `compare` command
+* Use the `compare` command:
 ```bash
 ## use compare to identify change(s)
 $ dotdrop compare --file=~/.vimrc
 ```
 
-* Call `update` with the `-P --show-patch` switch that will provide with an ad-hoc solution
-  to manually patch the template file using a temporary generated version of the template
-  (this isn't a bullet proof solution and might need manual checking)
+* Call `update` with the `-P`/`--show-patch` switch, which provides an ad-hoc solution
+  to manually patch the template file using a temporary generated version of the template.
+  (This isn't a bullet-proof solution and might need manual checking.)
 ```bash
 ## get an ad-hoc solution to manually patch the template
 $ dotdrop update --show-patch ~/.vimrc
@@ -213,7 +209,7 @@ $ dotdrop update --show-patch ~/.vimrc
 ```
 
 * Install the dotfiles to a temporary directory (using the `install` command and the
-  `-t` switch) and compare the generated dotfile with the local one.
+  `-t` switch) and compare the generated dotfile with the local one:
 ```bash
 ## use install to identify change(s)
 $ dotdrop install -t -t f_vimrc
@@ -223,17 +219,17 @@ $ diff ~/.vimrc /tmp/dotdrop-6ajz7565/home/user/.vimrc
 
 ## Remove dotfiles
 
-The command `remove` allows to stop managing a specific dotfile with
+The command `remove` allows you to stop managing a specific dotfile with
 dotdrop. It will:
 
-* remove the entry in the config file (under `dotfiles` and `profile`)
+* remove the entry from the config file (under `dotfiles` and `profile`)
 * remove the file from the `dotpath`
 
-For more options, see the usage with `dotdrop --help`
+For more options, see the usage with `dotdrop --help`.
 
 ## Concurrency
 
-The command line switch `-w --workers` if set to a value greater than one allows to use
+The command line switch `-w`/`--workers`, if set to a value greater than one, allows you to use
 multiple concurrent workers to execute an operation. It can be applied to the following
 commands:
 
@@ -244,37 +240,37 @@ commands:
 It should be set to a maximum of the number of cores available (usually returned
 on linux by the command `nproc`).
 
-It may speed up the operation but cannot be used interractively (it needs `-f --force` to be set
-except for `compare`) and cannot be used with `-d --dry`. Also information printed to stdout/stderr
+It may speed up the operation but cannot be used interactively (it needs `-f`/`--force` to be set
+except for `compare`) and cannot be used with `-d`/`--dry`. Also, information printed to stdout/stderr
 will probably be messed up.
 
-**WARNING** this feature hasn't been extensively tested and is to be used at your own risk.
-If you try it out and find any issue, please [report it](https://github.com/deadc0de6/dotdrop/issues).
-Also if you find it useful and have been able to successfully speed up your operation when using
-`-w --workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
+**WARNING:** This feature hasn't been extensively tested and is to be used at your own risk.
+If you try it out and find any issues, please [report them](https://github.com/deadc0de6/dotdrop/issues).
+Also, if you find it useful and have been able to successfully speed up your operation when using
+`-w`/`--workers`, do please also report it [in an issue](https://github.com/deadc0de6/dotdrop/issues).
 
 ## Environment variables
 
-Following environment variables can be used to specify different CLI options.
+The following environment variables can be used to specify different CLI options.
 Note that CLI switches take precedence over environment variables (except for `DOTDROP_FORCE_NODEBUG`)
 
-* `DOTDROP_PROFILE`: `-p --profile`
+* `DOTDROP_PROFILE`: `-p`/`--profile`
 ```bash
 export DOTDROP_PROFILE="my-fancy-profile"
 ```
-* `DOTDROP_CONFIG`: `-c --cfg`
+* `DOTDROP_CONFIG`: `-c`/`--cfg`
 ```bash
 export DOTDROP_CONFIG="/home/user/dotdrop/config.yaml"
 ```
-* `DOTDROP_NOBANNER`: `-b --no-banner`
+* `DOTDROP_NOBANNER`: `-b`/`--no-banner`
 ```bash
 export DOTDROP_NOBANNER=
 ```
-* `DOTDROP_DEBUG`: `-V --verbose`
+* `DOTDROP_DEBUG`: `-V`/`--verbose`
 ```bash
 export DOTDROP_DEBUG=
 ```
-* `DOTDROP_FORCE_NODEBUG`: disable debug outputs even if `-V --verbose` is provided or `DOTDROP_DEBUG` is set
+* `DOTDROP_FORCE_NODEBUG`: disable debug output even if `-V`/`--verbose` is provided or `DOTDROP_DEBUG` is set
 ```bash
 export DOTDROP_FORCE_NODEBUG=
 ```
@@ -286,7 +282,7 @@ export DOTDROP_TMPDIR="/tmp/dotdrop-tmp"
 ```bash
 export DOTDROP_WORKDIR="/tmp/dotdrop-workdir"
 ```
-* `DOTDROP_WORKERS`: overwrite the `-w --workers` cli argument
+* `DOTDROP_WORKERS`: overwrite the `-w`/`--workers` cli argument
 ```bash
 export DOTDROP_WORKERS="10"
 ```
@@ -303,7 +299,7 @@ such as a cache.
 Maybe you only want to change one file and don't want the others cluttering your repository.
 Maybe the program changes these files quite often and creates unnecessary diffs in your dotfiles.
 
-In these cases, you can use the [ingore-missing](config-format.md) option.
+In these cases, you can use the [ignore-missing](config-format.md) option.
 This option is available as a flag (`--ignore-missing` or `-z`) to the `update` and `compare` commands,
 or [as a configuration option either globally or on a specific dotfile](config-format.md).
 
diff --git a/tests-ng/README.md b/tests-ng/README.md
index ac7cad4..33de62f 100644
--- a/tests-ng/README.md
+++ b/tests-ng/README.md
@@ -1,8 +1,8 @@
 These are tests for testing entire behavior through shell scripts more easily than
-the overly complicated python tests.
+the overly complicated Python tests.
 
 For adding your own test, create a new script, copy the beginning of an
-existing test script (before the *this is the test*) and complete it
+existing test script (before the *this is the test*), and complete it
 with your test.
 
 Helper functions are available in `helpers`.