General documentation cleanup (#3317)

* Clean up spelling, grammar, perspective, whitespace, language, markup, etc.

6 files changed, 174 insertions, 102 deletions

diff --git a/docs/content/doc/advanced/config-cheat-sheet.en-us.md b/docs/content/doc/advanced/config-cheat-sheet.en-us.md
index 1615ee9c22..941e08a7ea 100644
--- a/docs/content/doc/advanced/config-cheat-sheet.en-us.md
+++ b/docs/content/doc/advanced/config-cheat-sheet.en-us.md
@@ -15,11 +15,17 @@ menu:
 
 # Configuration Cheat Sheet
 
-This is a cheat sheet for the Gitea configuration file. It contains all settings that can configured.
+This is a cheat sheet for the Gitea configuration file. It contains most settings
+that can configured as well as their default values.
 
-Any changes to the Gitea configuration file should be made in `custom/conf/app.ini` or any corresponding location. When installing from a distribution, this will typically be found at `/etc/gitea/conf/app.ini`.
+Any changes to the Gitea configuration file should be made in `custom/conf/app.ini`
+or any corresponding location. When installing from a distribution, this will
+typically be found at `/etc/gitea/conf/app.ini`.
 
-The defaults provided here are best-effort (not built automatically). They are accurately recorded in [app.ini.sample](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample) (s/master/<tag|release\>. Any string in the format `%(X)s` is a feature powered by [ini](https://github.com/go-ini/ini/#recursive-values), for reading values recursively.
+The defaults provided here are best-effort (not built automatically). They are
+accurately recorded in [app.ini.sample](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample)
+(s/master/<tag|release\>). Any string in the format `%(X)s` is a feature powered
+by [ini](https://github.com/go-ini/ini/#recursive-values), for reading values recursively.
 
 Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
 
@@ -28,22 +34,34 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
 ## Overall (`DEFAULT`)
 
 - `APP_NAME`: **Gitea: Git with a cup of tea**: Application name, used in the page title.
-- `RUN_USER`: **git**: The user Gitea will run as. This should be a dedicated service (non-user) account. Setting this incorrectly will cause Gitea to not start.
-- `RUN_MODE`: **dev**: For performance and other purposes, change this to `prod` when deployed to a production environment. The installation process will set this to `prod` automatically. \[prod, dev, test\]
+- `RUN_USER`: **git**: The user Gitea will run as. This should be a dedicated system
+   (non-user) account. Setting this incorrectly will cause Gitea to not start.
+- `RUN_MODE`: **dev**: For performance and other purposes, change this to `prod` when
+   deployed to a production environment. The installation process will set this to `prod`
+   automatically. \[prod, dev, test\]
 
 ## Repository (`repository`)
 
-- `ROOT`: **~/gitea-repositories/**: Root path for storing all repository data. It must be an absolute path.
-- `SCRIPT_TYPE`: **bash**: The script type your server supports, usually this is `bash`, but some users report that only `sh` is available.
+- `ROOT`: **~/gitea-repositories/**: Root path for storing all repository data. It must be
+   an absolute path.
+- `SCRIPT_TYPE`: **bash**: The script type this server supports, usually this is `bash`,
+   but some users report that only `sh` is available.
 - `ANSI_CHARSET`: **\<empty\>**: The default charset for an unrecognized charset.
 - `FORCE_PRIVATE`: **false**: Force every new repository to be private.
-- `DEFAULT_PRIVATE`: **last**: Default private when create a new repository. \[last, private, public\]
-- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user, `-1` means no limit.
-- `PULL_REQUEST_QUEUE_LENGTH`: **1000**: Length of pull request patch test queue, make it as large as possible. Use caution when editing this value.
-- `MIRROR_QUEUE_LENGTH`: **1000**: Patch test queue length, increase if pull request patch testing starts hanging.
-- `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: Preferred Licenses to place at the top of the List. Name must match file name in conf/license or custom/conf/license.
-- `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the HTTP protocol.
-- `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when default SSH port is used.
+- `DEFAULT_PRIVATE`: **last**: Default private when creating a new repository.
+   \[last, private, public\]
+- `MAX_CREATION_LIMIT`: **-1**: Global maximum creation limit of repositories per user,
+   `-1` means no limit.
+- `PULL_REQUEST_QUEUE_LENGTH`: **1000**: Length of pull request patch test queue, make it
+   as large as possible. Use caution when editing this value.
+- `MIRROR_QUEUE_LENGTH`: **1000**: Patch test queue length, increase if pull request patch
+   testing starts hanging.
+- `PREFERRED_LICENSES`: **Apache License 2.0,MIT License**: Preferred Licenses to place at
+   the top of the list. Name must match file name in conf/license or custom/conf/license.
+- `DISABLE_HTTP_GIT`: **false**: Disable the ability to interact with repositories over the
+   HTTP protocol.
+- `USE_COMPAT_SSH_URI`: **false**: Force ssh:// clone url instead of scp-style uri when
+   default SSH port is used.
 
 ## UI (`ui`)
 
@@ -60,40 +78,43 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
 
 ## Markdown (`markdown`)
 
-- `ENABLE_HARD_LINE_BREAK`: **false**: Whether or not to enable hard the line break extension.
+- `ENABLE_HARD_LINE_BREAK`: **false**: Enable Markdown's hard line break extension.
 
 ## Server (`server`)
 
-- `PROTOCOL`: **http**: Either `http`, `https`, `fcgi`, or `unix`.
-- `DOMAIN`: **localhost**: Domain name of your server.
+- `PROTOCOL`: **http**: \[http, https, fcgi, unix\]
+- `DOMAIN`: **localhost**: Domain name of this server.
 - `ROOT_URL`: **%(PROTOCOL)s://%(DOMAIN)s:%(HTTP\_PORT)s/**: Full public URL of Gitea server.
 - `HTTP_ADDR`: **0.0.0.0**: HTTP listen address.
-   - If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
+   - If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket
+     defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
    - If `PROTOCOL` is set to `unix`, this should be the name of the Unix socket file to use.
 - `HTTP_PORT`: **3000**: HTTP listen port.
-   - If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
-- `UNIX_SOCKET_PERMISSION`: **666**: Permisson mode for Unix socket.
-- `DISABLE_SSH`: **false**: Disables SSH feature when it's not available.
-- `START_SSH_SERVER`: **false**: When enabled, uses the built-in SSH server.
-- `SSH_DOMAIN`: **%(DOMAIN)s**: Domain name of your ssh server, used for displayed clone URL.
+   - If `PROTOCOL` is set to `fcgi`, Gitea will listen for FastCGI requests on TCP socket
+     defined by `HTTP_ADDR` and `HTTP_PORT` configuration settings.
+- `UNIX_SOCKET_PERMISSION`: **666**: Permissions for the Unix socket.
+- `DISABLE_SSH`: **false**: Disable SSH feature when it's not available.
+- `START_SSH_SERVER`: **false**: When enabled, use the built-in SSH server.
+- `SSH_DOMAIN`: **%(DOMAIN)s**: Domain name of this server, used for displayed clone URL.
 - `SSH_PORT`: **22**: SSH port displayed in clone URL.
 - `SSH_LISTEN_PORT`: **%(SSH\_PORT)s**: Port for the built-in SSH server.
 - `OFFLINE_MODE`: **false**: Disables use of CDN for static files and Gravatar for profile pictures.
-- `DISABLE_ROUTER_LOG`: **false**: Mutes printing of the router log.
+- `DISABLE_ROUTER_LOG`: **false**: Mute printing of the router log.
 - `CERT_FILE`: **custom/https/cert.pem**: Cert file path used for HTTPS.
 - `KEY_FILE`: **custom/https/key.pem**: Key file path used for HTTPS.
 - `STATIC_ROOT_PATH`: **./**: Upper level of template and static files path.
 - `ENABLE_GZIP`: **false**: Enables application-level GZIP support.
-- `LANDING_PAGE`: **home**: Landing page for unauthenticated users, either `home` or `explore`.
+- `LANDING_PAGE`: **home**: Landing page for unauthenticated users  \[home, explore\].
 - `LFS_START_SERVER`: **false**: Enables git-lfs support.
-- `LFS_CONTENT_PATH`: **./data/lfs**: Where to store lfs files.
+- `LFS_CONTENT_PATH`: **./data/lfs**: Where to store LFS files.
 - `LFS_JWT_SECRET`: **\<empty\>**: LFS authentication secret, change this a unique string.
-- `REDIRECT_OTHER_PORT`: **false**: If true and `PROTOCOL` is https, redirects http requests on another (https) port.
+- `REDIRECT_OTHER_PORT`: **false**: If true and `PROTOCOL` is https, redirects http requests
+   on another (https) port.
 - `PORT_TO_REDIRECT`: **80**: Port used when `REDIRECT_OTHER_PORT` is true.
 
 ## Database (`database`)
 
-- `DB_TYPE`: **mysql**: The database type you choose, either `mysql`, `postgres`, `mssql` or `sqlite3`.
+- `DB_TYPE`: **mysql**: The database type in use \[mysql, postgres, mssql, sqlite3\].
 - `HOST`: **127.0.0.1:3306**: Database host address and port.
 - `NAME`: **gitea**: Database name.
 - `USER`: **root**: Database username.
@@ -111,31 +132,41 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
 
 ## Security (`security`)
 
-- `INSTALL_LOCK`: **false**: Disable to allow accessing the install page.
-- `SECRET_KEY`: **random at every install**: Global secret key. This should be changed.
+- `INSTALL_LOCK`: **false**: Disallow access to the install page.
+- `SECRET_KEY`: **\<random at every install\>**: Global secret key. This should be changed.
 - `LOGIN_REMEMBER_DAYS`: **7**: Cookie lifetime, in days.
 - `COOKIE_USERNAME`: **gitea\_awesome**: Name of the cookie used to store the current username.
-- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication information.
-- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy authentication.
-- `DISABLE_GIT_HOOKS`: **false**: Prevent all users (including admin) from creating custom git hooks.
+- `COOKIE_REMEMBER_NAME`: **gitea\_incredible**: Name of cookie used to store authentication
+   information.
+- `REVERSE_PROXY_AUTHENTICATION_USER`: **X-WEBAUTH-USER**: Header name for reverse proxy
+   authentication.
+- `DISABLE_GIT_HOOKS`: **false**: Prevent all users (including admin) from creating custom
+   git hooks.
 
 ## OpenID (`openid`)
 
 - `ENABLE_OPENID_SIGNIN`: **false**: Allow authentication in via OpenID.
 - `ENABLE_OPENID_SIGNUP`: **! DISABLE\_REGISTRATION**: Allow registering via OpenID.
-- `WHITELISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching OpenID URI's to permit.
-- `BLACKLISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching OpenID URI's to block.
+- `WHITELISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching
+   OpenID URI's to permit.
+- `BLACKLISTED_URIS`: **\<empty\>**: If non-empty, list of POSIX regex patterns matching
+   OpenID URI's to block.
 
 ## Service (`service`)
 
 - `ACTIVE_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm account/email registration.
-- `RESET_PASSWD_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm forgot password reset process.
-- `REGISTER_EMAIL_CONFIRM`: **false**: Enable this to ask for mail confirmation of registration. Requires `Mailer` to be enabled.
-- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create accounts for users.
+- `RESET_PASSWD_CODE_LIVE_MINUTES`: **180**: Time limit (min) to confirm forgot password reset
+   process.
+- `REGISTER_EMAIL_CONFIRM`: **false**: Enable this to ask for mail confirmation of registration.
+   Requires `Mailer` to be enabled.
+- `DISABLE_REGISTRATION`: **false**: Disable registration, after which only admin can create
+   accounts for users.
 - `REQUIRE_SIGNIN_VIEW`: **false**: Enable this to force users to log in to view any page.
-- `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when something happens, like creating issues. Requires `Mailer` to be enabled.
+- `ENABLE_NOTIFY_MAIL`: **false**: Enable this to send e-mail to watchers of a repository when
+   something happens, like creating issues. Requires `Mailer` to be enabled.
 - `ENABLE_REVERSE_PROXY_AUTHENTICATION`: **false**: Enable this to allow reverse proxy authentication.
-- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration for reverse authentication.
+- `ENABLE_REVERSE_PROXY_AUTO_REGISTRATION`: **false**: Enable this to allow auto-registration
+   for reverse authentication.
 - `ENABLE_CAPTCHA`: **true**: Enable this to use captcha validation for registration.
 
 ## Webhook (`webhook`)
@@ -151,43 +182,52 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
 - `DISABLE_HELO`: **\<empty\>**: Disable HELO operation.
 - `HELO_HOSTNAME`: **\<empty\>**: Custom hostname for HELO operation.
 - `HOST`: **\<empty\>**: SMTP mail host address and port (example: smtp.gitea.io:587).
-- `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or the "Name" \<email@example.com\> format.
+- `FROM`: **\<empty\>**: Mail from address, RFC 5322. This can be just an email address, or
+   the "Name" \<email@example.com\> format.
 - `USER`: **\<empty\>**: Username of mailing user (usually the sender's e-mail address).
 - `PASSWD`: **\<empty\>**: Password of mailing user.
 - `SKIP_VERIFY`: **\<empty\>**: Do not verify the self-signed certificates.
    - **Note:** Gitea only supports SMTP with STARTTLS.
-- `USE_SENDMAIL`: **false** Use the operating system's `sendmail` command instead of SMTP. This is common on linux systems.
-   - Note that enabling sendmail will ignore all other `mailer` settings except `ENABLED`, `FROM` and `SENDMAIL_PATH`.
-- `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system. (can be command or full path)
+- `USE_SENDMAIL`: **false** Use the operating system's `sendmail` command instead of SMTP.
+   This is common on linux systems.
+   - Note that enabling sendmail will ignore all other `mailer` settings except `ENABLED`,
+     `FROM` and `SENDMAIL_PATH`.
+- `SENDMAIL_PATH`: **sendmail**: The location of sendmail on the operating system. (can be
+   command or full path)
 
 ## Cache (`cache`)
 
-- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, or `memcache`. If you want to use `redis` or `memcache`, be sure to rebuild everything with build tags `redis` or `memcache`: `go build -tags='redis'`.
+- `ADAPTER`: **memory**: Cache engine adapter, either `memory`, `redis`, or `memcache`.
+   - To use `redis` or `memcache`, be sure to rebuild everything with build tags `redis` or
+     `memcache`: `go build -tags='redis'`.
 - `INTERVAL`: **60**: Garbage Collection interval (sec), for memory cache only.
 - `HOST`: **\<empty\>**: Connection string for `redis` and `memcache`.
-    - Redis: `network=tcp,addr=127.0.0.1:6379,password=macaron,db=0,pool_size=100,idle_timeout=180`
-    - Memache: `127.0.0.1:9090;127.0.0.1:9091`
+   - Redis: `network=tcp,addr=127.0.0.1:6379,password=macaron,db=0,pool_size=100,idle_timeout=180`
+   - Memache: `127.0.0.1:9090;127.0.0.1:9091`
 
 ## Session (`session`)
 
-- `PROVIDER`: **memory**: Session engine provider, either `memory`, `file`, `redis`, or `mysql`.
+- `PROVIDER`: **memory**: Session engine provider \[memory, file, redis, mysql\].
 - `PROVIDER_CONFIG`: **data/sessions**: For file, the root path; for others, the connection string.
 - `COOKIE_SECURE`: **false**: Enable this to force using HTTPS for all session access.
-- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID, defaults to `i_like_gitea`.
+- `COOKIE_NAME`: **i\_like\_gitea**: The name of the cookie used for the session ID.
 - `GC_INTERVAL_TIME`: **86400**: GC interval in seconds.
 
 ## Picture (`picture`)
 
-- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo` or anything like `http://cn.gravatar.com/avatar/`.
+- `GRAVATAR_SOURCE`: **gravatar**: Can be `gravatar`, `duoshuo` or anything like
+   `http://cn.gravatar.com/avatar/`.
 - `DISABLE_GRAVATAR`: **false**: Enable this to use local avatars only.
-- `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see http://www.libravatar.org)
+- `ENABLE_FEDERATED_AVATAR`: **false**: Enable support for federated avatars (see
+   http://www.libravatar.org)
 - `AVATAR_UPLOAD_PATH`: **data/avatars**: Path to store local and cached files.
 
 ## Attachment (`attachment`)
 
 - `ENABLED`: **true**: Enable this to allow uploading attachments.
 - `PATH`: **data/attachments**: Path to store attachments.
-- `ALLOWED_TYPES`: **see app.ini.sample**: Allowed MIME types, e.g. `image/jpeg|image/png`, use `*/*` for all types.
+- `ALLOWED_TYPES`: **see app.ini.sample**: Allowed MIME types, e.g. `image/jpeg|image/png`.
+   Use `*/*` for all types.
 - `MAX_SIZE`: **4**: Maximum size (MB).
 - `MAX_FILES`: **5**: Maximum number of attachments that can be uploaded at once.
 
@@ -231,10 +271,9 @@ Values containing `#` or `;` must be quoted using `` ` `` or `"""`.
 - `MAX_GIT_DIFF_FILES`: **100**: Max number of files shown in diff view.
 - `GC_ARGS`: **\<empty\>**: Arguments for command `git gc`, e.g. `--aggressive --auto`.
 
-## markup (`markup`)
+## Markup (`markup`)
 
-Gitea supports external markup support, you can integrate all your favorite tool. For example,
-below will add a markup named `asciidoc` which is followed `markup.` ini section. And there are some config items below.
+Gitea can support Markup using external tools. The example below will add a markup named `asciidoc`.
 
 ```ini
 [markup.asciidoc]
@@ -244,10 +283,11 @@ RENDER_COMMAND = "asciidoc --out-file=- -"
 IS_INPUT_FILE = false
 ```
 
-- ENABLED: Whether enable this tool. default is false.
-- FILE_EXTENSIONS: List of file extensions that should be rendered by an external command.  Multiple extentions needs a comma as splitter.
-- RENDER_COMMAND: External command to render all matching extensions.
-- IS_INPUT_FILE: Input is not a standard input but a file param followed `RENDER_COMMAND`, default is false.
+- ENABLED: **false** Enable markup support.
+- FILE\_EXTENSIONS: **\<empty\>** List of file extensions that should be rendered by an external
+   command. Multiple extentions needs a comma as splitter.
+- RENDER\_COMMAND: External command to render all matching extensions.
+- IS\_INPUT\_FILE: **false** Input is not a standard input but a file param followed `RENDER_COMMAND`.
 
 ## Other (`other`)
 
diff --git a/docs/content/doc/advanced/customizing-gitea.en-us.md b/docs/content/doc/advanced/customizing-gitea.en-us.md
index 8c861757ff..5be30740c2 100644
--- a/docs/content/doc/advanced/customizing-gitea.en-us.md
+++ b/docs/content/doc/advanced/customizing-gitea.en-us.md
@@ -15,42 +15,57 @@ menu:
 
 # Customizing Gitea
 
-The main way to customize Gitea is by using the `custom` folder. This is the central place to override and configure features.
+Customizing Gitea is typically done using the `custom` folder. This is the central
+place to override configuration settings, templates, etc.
 
-If you install Gitea from binary, after the installation process ends, you can find the `custom` folder next to the binary.
-Gitea will create the folder for you and prepopulate it with a `conf` folder inside, where Gitea stores all the configuration settings provided through the installation steps (have a look [here](https://docs.gitea.io/en-us/config-cheat-sheet/) for a complete list).
+If Gitea is deployed from binary, all default paths will be relative to the gitea
+binary. If installed from a distribution, these paths will likely be modified to
+the Linux Filesystem Standard. Gitea will create required folders, including `custom/`.
+Application settings are configured in `custom/conf/app.ini`. Distributions may
+provide a symlink for `custom` using `/etc/gitea/`.
 
-If you can't find the `custom` folder next to the binary, please check the `GITEA_CUSTOM` environment variable, that can be used to override the default path to something else. `GITEA_CUSTOM` might be set for example in your launch script file. Please have a look [here](https://docs.gitea.io/en-us/specific-variables/) for a complete list of environment variables.
+- [Quick Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/)
+- [Complete List](https://github.com/go-gitea/gitea/blob/master/custom/conf/app.ini.sample)
 
-**Note** that you have to restart Gitea for it to notice the changes.
+If the `custom` folder can't be found next to the binary, check the `GITEA_CUSTOM`
+environment variable; this can be used to override the default path to something else.
+`GITEA_CUSTOM` might, for example, be set by an init script.
+
+- [List of Environment Variables](https://docs.gitea.io/en-us/specific-variables/)
+
+**Note:** Gitea must perform a full restart to see configuration changes.
 
 ## Customizing /robots.txt
 
-To make Gitea serve your own `/robots.txt` (by default, an empty 404 status is served), simply create a file called `robots.txt` in the `custom` folder with the [expected contents](http://www.robotstxt.org/).
+To make Gitea serve a custom `/robots.txt` (default: empty 404), create a file called
+`robots.txt` in the `custom` folder with [expected contents](http://www.robotstxt.org/).
 
 ## Serving custom public files
 
-To make Gitea serve custom public files (like pages and images), use the folder `custom/public/` as the webroot. Symbolic links will be followed.
+To make Gitea serve custom public files (like pages and images), use the folder
+`custom/public/` as the webroot. Symbolic links will be followed.
 
-For example, a file `image.png` stored in `custom/public`, can be accessed with the url `http://your-gitea-url/image.png`.
+For example, a file `image.png` stored in `custom/public/`, can be accessed with
+the url `http://gitea.domain.tld/image.png`.
 
 ## Changing the default avatar
 
-Place the png image at the following path: `custom/public/img/avatar_default.png`
+Place the png image at the following path: `custom/public/img/avatar\_default.png`
 
 ## Customizing Gitea pages
 
-The `custom/templates` folder allows you to change every single page of Gitea.
-
-You need to be aware of the template you want to change. All templates can be found in the `templates` folder of the Gitea sources.
-
-When you find the correct .tmpl file, you need to copy it in the `custom/templates` folder of your installation, __respecting__ any subfolder you found in the source template.
+The `custom/templates` folder allows changing every single page of Gitea. Templates
+to override can be found in the `templates` directory of Gitea source. Override by
+making a copy of the file under `custom/templates` using a full path structure
+matching source.
 
-You can now customize the template you copied in `custom/templates`, being carefully to not break the Gitea syntax.
-Any statement contained inside `{{` and `}}` are Gitea templete's syntax and shouldn't be touch, unless you know what are you doing.
+Any statement contained inside `{{` and `}}` are Gitea's templete syntax and
+shouldn't be touched without fully understanding these components.
 
-To add in custom HTML to the header or the footer of the page, in the `templates/custom` directory there are `header.tmpl` and `footer.tmpl` that can be modified. This is useful if you want to add in custom CSS files, or additional Javascript.
+To add custom HTML to the header or the footer of the page, in the `templates/custom`
+directory there is `header.tmpl` and `footer.tmpl` that can be modified. This can be
+a useful place to add custom CSS files or additional Javascript.
 
 ## Customizing gitignores, labels, licenses, locales, and readmes.
 
-Place your own files in corresponding sub-folder under `custom/options`.
\ No newline at end of file
+Place custom files in corresponding sub-folder under `custom/options`.
diff --git a/docs/content/doc/advanced/hacking-on-gitea.en-us.md b/docs/content/doc/advanced/hacking-on-gitea.en-us.md
index 368d174491..469c5a5021 100644
--- a/docs/content/doc/advanced/hacking-on-gitea.en-us.md
+++ b/docs/content/doc/advanced/hacking-on-gitea.en-us.md
@@ -15,21 +15,28 @@ menu:
 
 # Hacking on Gitea
 
-We won't cover the basics of a Golang setup within this guide. If you don't know how to get the environment up and running you should follow the official [install instructions](https://golang.org/doc/install).
+Familiarity with the existing [installation instructions](https://golang.org/doc/install)
+is required for this section.
 
-If you want to contribute to Gitea you should fork the project and work on the `master` branch. There is a catch though, some internal packages are referenced by their GitHub URL. So you have to trick the Go tool to think that you work on a clone of the official repository. Start by downloading the source code as you normally would:
+To contribute to Gitea, fork the project and work on the `master` branch.
+
+Some internal packages are referenced using their respective Github URL. This can
+become problematic. To "trick" the Go tool into thinking this is a clone from the
+official repository, download the source code using "go get" and follow these instructions.
 
 ```
 go get -d code.gitea.io/gitea
 ```
 
-Now it's time to fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub, after that you should have to switch to the source directory on the command line:
+Fork the [Gitea repository](https://github.com/go-gitea/gitea) on GitHub, it should
+then be possible to switch the source directory on the command line.
 
 ```
 cd $GOPATH/src/code.gitea.io/gitea
 ```
 
-To be able to create pull requests you should add your forked repository as a remote to the Gitea sources, otherwise you can not apply the changes to our repository because of lacking write permissions:
+To be able to create pull requests, the forked repository should be added as a remote
+to the Gitea sources, otherwise changes can't be pushed.
 
 ```
 git remote rename origin upstream
@@ -37,6 +44,12 @@ git remote add origin git@github.com:<USERNAME>/gitea.git
 git fetch --all --prune
 ```
 
-You've got a working development environment for Gitea now. Take a look at the `Makefile` to get an overview about the available tasks. The most common tasks should be `make test` which will start our test environment and `make build` which will build a `gitea` binary into your working directory. Writing test cases is not mandatory to contribute, but we will be happy if you do.
+This should provide a working development environment for Gitea. Take a look at
+the `Makefile` to get an overview about the available tasks. The most common tasks
+should be `make test` which will start our test environment and `make build` which
+will build a `gitea` binary into the working directory. Writing test cases is not
+mandatory to contribute, but it is highly encouraged and helps developers sleep
+at night.
 
-That’s it! You are ready to hack on Gitea. Test your changes, push them to your repository and open a pull request.
+That's it! You are ready to hack on Gitea. Test changes, push them to the repository,
+and open a pull request.
diff --git a/docs/content/doc/advanced/make.en-us.md b/docs/content/doc/advanced/make.en-us.md
index 836c544397..f90367de59 100644
--- a/docs/content/doc/advanced/make.en-us.md
+++ b/docs/content/doc/advanced/make.en-us.md
@@ -15,16 +15,17 @@ menu:
 
 # Make
 
-Gitea makes heavy use of Make to automate tasks and have a faster development. This guide cover how to install Make.
+Gitea makes heavy use of Make to automate tasks and improve development. This
+guide covers how to install Make.
 
 ### On Linux
 
-You can install with your package manager. 
+Install with the package manager.
 
 On Ubuntu/Debian:
 
 ```bash
-sudo apt-get install build-essential
+sudo apt-get install make
 ```
 
 On Fedora/RHEL/CentOS:
@@ -35,10 +36,11 @@ sudo yum install make
 
 ### On Windows
 
-If you are using Windows, you can download and use one of these distributions of Make:
+One of these three distributions of Make will run on Windows:
 
 - [Single binary build](http://www.equation.com/servlet/equation.cmd?fa=make). Copy somewhere and add to `PATH`.
   - [32-bits version](ftp://ftp.equation.com/make/32/make.exe)
   - [64-bits version](ftp://ftp.equation.com/make/64/make.exe)
-- [MinGW](http://www.mingw.org/) includes a build. The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to your `PATH`.
+- [MinGW](http://www.mingw.org/) includes a build.
+  - The binary is called `mingw32-make.exe` instead of `make.exe`. Add the `bin` folder to `PATH`.
 - [Chocolatey package](https://chocolatey.org/packages/make). Run `choco install make`
diff --git a/docs/content/doc/advanced/make.fr-fr.md b/docs/content/doc/advanced/make.fr-fr.md
index 427a8fc68f..427a8fc68f 100755..100644
--- a/docs/content/doc/advanced/make.fr-fr.md
+++ b/docs/content/doc/advanced/make.fr-fr.md
diff --git a/docs/content/doc/advanced/specific-variables.en-us.md b/docs/content/doc/advanced/specific-variables.en-us.md
index 1fe705aa72..8dbe9a8cf5 100644
--- a/docs/content/doc/advanced/specific-variables.en-us.md
+++ b/docs/content/doc/advanced/specific-variables.en-us.md
@@ -25,43 +25,45 @@ GITEA_CUSTOM=/home/gitea/custom ./gitea web
 
 ## From Go language
 
-As Gitea is written in Go, it uses some Go variables as:
+As Gitea is written in Go, it uses some Go variables, such as:
 
   * `GOOS`
   * `GOARCH`
-  * `GOPATH`
+  * [`GOPATH`](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable)
 
-For `GOPATH`, check [official documentation about GOPATH environment variable](https://golang.org/cmd/go/#hdr-GOPATH_environment_variable).
-
-For others, check [official documentation about variables used when it runs the generator](https://golang.org/cmd/go/#hdr-Generate_Go_files_by_processing_source).
+For documentation about each of the variables available, refer to the
+[official Go documentation](https://golang.org/cmd/go/#hdr-Environment_variables).
 
 ## Gitea files
 
-  * `GITEA_WORK_DIR`: Gitea absolute path of work directory.
-  * `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable to change *custom* directory.
+  * `GITEA_WORK_DIR`: Absolute path of working directory.
+  * `GITEA_CUSTOM`: Gitea uses `GITEA_WORK_DIR`/custom folder by default. Use this variable
+     to change *custom* directory.
   * `GOGS_WORK_DIR`: Deprecated, use `GITEA_WORK_DIR`
   * `GOGS_CUSTOM`: Deprecated, use `GITEA_CUSTOM`
 
 ## Operating system specifics
 
-  * `USER`: system user that launch Gitea. Useful for repository URL address on Gitea interface
-  * `USERNAME`: if no USER found, Gitea will try `USERNAME`
-  * `HOME`: User home directory path (**except if** you're running on Windows, check  the following `USERPROFILE` variable)
+  * `USER`: System user that Gitea will run as. Used for some repository access strings.
+  * `USERNAME`: if no `USER` found, Gitea will use `USERNAME`
+  * `HOME`: User home directory path. The `USERPROFILE` environment variable is used in Windows.
 
 ### Only on Windows
 
   * `USERPROFILE`: User home directory path. If empty, uses `HOMEDRIVE` + `HOMEPATH`
-  * `HOMEDRIVE`: Main drive path you will use to get home directory
+  * `HOMEDRIVE`: Main drive path used to access the home directory (C:)
   * `HOMEPATH`: Home relative path in the given home drive path
 
 ## Macaron (framework used by Gitea)
 
   * `HOST`: Host Macaron will listen on
   * `PORT`: Port Macaron will listen on
-  * `MACARON_ENV`: global variable to provide special functionality for development environments vs production environments. If MACARON_ENV is set to "" or "development" then templates will be recompiled on every request. For more performance, set the MACARON_ENV environment variable to "production".
+  * `MACARON_ENV`: global variable to provide special functionality for development environments
+     vs. production environments. If MACARON_ENV is set to "" or "development" then templates will
+     be recompiled on every request. For more performance, set the MACARON_ENV environment variable
+     to "production".
 
 ## Miscellaneous
 
-  * `SKIP_MINWINSVC`: Do not run as a service on Windows if set to 1
+  * `SKIP_MINWINSVC`: If set to 1, do not run as a service on Windows.
   * `ZOOKEEPER_PATH`: [Zookeeper](http://zookeeper.apache.org/) jar file path
-