General documentation cleanup (#3317)

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

11 files changed, 140 insertions, 87 deletions

diff --git a/docs/content/doc/installation/from-binary.en-us.md b/docs/content/doc/installation/from-binary.en-us.md
index f47f1de3fb..91f81f73f1 100644
--- a/docs/content/doc/installation/from-binary.en-us.md
+++ b/docs/content/doc/installation/from-binary.en-us.md
@@ -15,7 +15,10 @@ menu:
 
 # Installation from binary
 
-All downloads come with SQLite, MySQL and PostgreSQL support, and are built with embedded assets. Keep in mind that this can be different for older releases. The installation based on our binaries is quite simple, just choose the file matching your platform from the [downloads page](https://dl.gitea.io/gitea), copy the URL and replace the URL within the commands below:
+All downloads come with SQLite, MySQL and PostgreSQL support, and are built with
+embedded assets. This can be different for older releases. Choose the file matching
+the destination platform from the [downloads page](https://dl.gitea.io/gitea), copy
+the URL and replace the URL within the commands below:
 
 ```
 wget -O gitea https://dl.gitea.io/gitea/1.3.2/gitea-1.3.2-linux-amd64
@@ -24,7 +27,8 @@ chmod +x gitea
 
 ## Test
 
-After following the steps above you will have a `gitea` binary within your working directory, first you can test it if it works like expected and afterwards you can copy it to the destination where you want to store it. When you launch Gitea manually from your CLI you can always kill it by hitting `Ctrl + C`.
+After getting a binary, it can be tested with `./gitea web` or moved to a permanent
+location. When launched manually, Gitea can be killed using `Ctrl+C`.
 
 ```
 ./gitea web
@@ -34,12 +38,16 @@ After following the steps above you will have a `gitea` binary within your worki
 
 ### Old glibc versions
 
-Older Linux distributions (such as Debian 7 and CentOS 6) may not be able to load the Gitea binary, usually resulting an error like ```./gitea: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.14' not found (required by ./gitea)```. This is due to the integrated SQLite support in the binaries we provide. In the future, we will provide binaries without the requirement for glibc. As a workaround, you can upgrade your distribution or [install from source]({{< relref "from-source.en-us.md" >}}).
+Older Linux distributions (such as Debian 7 and CentOS 6) may not be able to load the
+Gitea binary, usually producing an error such as ```./gitea: /lib/x86_64-linux-gnu/libc.so.6:
+version `GLIBC\_2.14' not found (required by ./gitea)```. This is due to the integrated
+SQLite support in the binaries provided by dl.gitea.io. In this situation, it is usually
+possible to [install from source]({{< relref "from-source.en-us.md" >}}) without sqlite
+support.
 
 ### Running gitea on another port
 
-If getting an error like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000: bind: address already in use` gitea needs to be started on another free port. This is possible using `./gitea web -p $PORT`.
-
-## Anything missing?
-
-Are we missing anything on this page? Then feel free to reach out to us on our [Discord server](https://discord.gg/NsatcWJ), there you will get answers to any question pretty fast.
+For errors like `702 runWeb()] [E] Failed to start server: listen tcp 0.0.0.0:3000:
+bind: address already in use` gitea needs to be started on another free port. This
+is possible using `./gitea web -p $PORT`. It's possible another instance of gitea
+is already running.
diff --git a/docs/content/doc/installation/from-binary.fr-fr.md b/docs/content/doc/installation/from-binary.fr-fr.md
index 6cf9c03998..6cf9c03998 100755..100644
--- a/docs/content/doc/installation/from-binary.fr-fr.md
+++ b/docs/content/doc/installation/from-binary.fr-fr.md
diff --git a/docs/content/doc/installation/from-package.en-us.md b/docs/content/doc/installation/from-package.en-us.md
index 94f0815d3e..9fdf30d79f 100644
--- a/docs/content/doc/installation/from-package.en-us.md
+++ b/docs/content/doc/installation/from-package.en-us.md
@@ -15,17 +15,30 @@ menu:
 
 # Installation from package
 
-## Linux
+## Debian
 
-We have not published any real package yet, we will update this page directly when we start to publish packages for any Linux distribution, in the meantime you should follow our [installation from binary]({{< relref "from-binary.en-us.md" >}}) guide.
+The only distribution that has any "official" package of Gitea is Debian. This is currently
+in Debian's [contrib](https://wiki.debian.org/SourcesList). This is (currently) only available
+in Debian testing and unstable (but should be installable/functional on stable).
+
+- Edit /etc/apt/sourced.list
+   - Add "contrib" to "deb http://deb.debian.org/debian unstable main contrib"
+- apt-get update
+- apt-get install gitea
+
+For other distributions, see the [deployment from binary]({{< relref "from-binary.en-us.md" >}}) guide.
 
 ## Windows
 
-We have not published any package for Windows yet, we will update this page directly when we start to publish packages in the form of `MSI` installers or via [Chocolatey](https://chocolatey.org/), in the meantime you should follow our [installation from binary]({{< relref "from-binary.en-us.md" >}}) guide.
+There are no published packages for Windows. This page will change when packages are published,
+in the form of `MSI` installers or via [Chocolatey](https://chocolatey.org/). In the meantime
+the [deployment from binary]({{< relref "from-binary.en-us.md" >}}) guide.
 
 ## macOS
 
-Currently we only support the installation via `brew` for macOS. If you are not using [Homebrew](http://brew.sh/) you should follow our [installation from binary]({{< relref "from-binary.en-us.md" >}}) guide. To install Gitea via `brew` you just need to execute the following commands:
+Currently, the only supported method of installation on MacOS is [Homebrew](http://brew.sh/).
+Following the [deployment from binary]({{< relref "from-binary.en-us.md" >}}) guide may work,
+but is not supported. To install Gitea via `brew`:
 
 ```
 brew tap go-gitea/gitea
@@ -34,13 +47,14 @@ brew install gitea
 
 ## FreeBSD
 
-A FreeBSD port `www/gitea` is available.  You can install a pre-built binary package:
+A FreeBSD port `www/gitea` is available. To install the pre-built binary package:
 
 ```
 pkg install gitea
 ```
 
-For the most up to date version, or to build the port with custom options, [install it from the port](https://www.freebsd.org/doc/handbook/ports-using.html):
+For the most up to date version, or to build the port with custom options,
+[install it from the port](https://www.freebsd.org/doc/handbook/ports-using.html):
 
 ```
 su -
@@ -48,10 +62,8 @@ cd /usr/ports/www/gitea
 make install clean
 ```
 
-The port uses the standard FreeBSD file system layout: config files are in `/usr/local/etc/gitea`, bundled templates, options, plugins and themes are in `/usr/local/share/gitea`, and a start script is in `/usr/local/etc/rc.d/gitea`.
-
-To enable Gitea to run as a service, run `sysrc gitea_enable=YES` and start it with `service gitea start`. 
-
-## Anything missing?
+The port uses the standard FreeBSD file system layout: config files are in `/usr/local/etc/gitea`,
+bundled templates, options, plugins and themes are in `/usr/local/share/gitea`, and a start script
+is in `/usr/local/etc/rc.d/gitea`.
 
-Are we missing anything on this page? Then feel free to reach out to us on our [Discord server](https://discord.gg/NsatcWJ), there you will get answers to any question pretty fast.
+To enable Gitea to run as a service, run `sysrc gitea_enable=YES` and start it with `service gitea start`.
diff --git a/docs/content/doc/installation/from-package.fr-fr.md b/docs/content/doc/installation/from-package.fr-fr.md
index 4e8149236e..4e8149236e 100755..100644
--- a/docs/content/doc/installation/from-package.fr-fr.md
+++ b/docs/content/doc/installation/from-package.fr-fr.md
diff --git a/docs/content/doc/installation/from-source.en-us.md b/docs/content/doc/installation/from-source.en-us.md
index a6686d8bd8..b4f804fd64 100644
--- a/docs/content/doc/installation/from-source.en-us.md
+++ b/docs/content/doc/installation/from-source.en-us.md
@@ -15,52 +15,66 @@ menu:
 
 # Installation from source
 
-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).
+This section will not include basic [installation instructions](https://golang.org/doc/install).
 
 **Note**: Go version 1.7 or higher is required
 
 ## Download
 
-First of all you have to retrieve the source code, the easiest way is to simply use directly Go for that. Just call the following commands to fetch the source and to switch into the working directory.
+First retrieve the source code. The easiest way is to use the Go tool. Use the following
+commands to fetch the source and switch into the source directory.
 
 ```
 go get -d -u code.gitea.io/gitea
 cd $GOPATH/src/code.gitea.io/gitea
 ```
 
-Now it's time to decide which version of Gitea you want to build and install. Currently there are multiple options you can choose from. If you want to build our `master` branch you can directly go ahead to the [build section](#build), this branch represents our current development version and this is not intended for production use.
-
-If you want to build the latest stable version that acts as a development branch for the tagged releases you can see the available branches and how to checkout this branch with these commands:
+Decide which version of Gitea to build and install. Currently, there are multiple options
+to choose from. The `master` branch represents the current development version. To build
+with master, skip to the [build section](#build).
 
+To work with tagged releases, the following commands can be used:
 ```
 git branch -a
 git checkout v1.0
 ```
 
-If you would validate a Pull Request, first your must enable this new branch : (`xyz` is the PR id, for example `2663` for [#2663](https://github.com/go-gitea/gitea/pull/2663))
+To validate a Pull Request, first enable the new branch (`xyz` is the PR id; for example
+`2663` for [#2663](https://github.com/go-gitea/gitea/pull/2663)):
 
 ```
 git fetch origin pull/xyz/head:pr-xyz
 ```
 
-Last but not least you can also directly build our tagged versions like `v1.0.0`, if you want to build Gitea from the source this is the suggested way for that. To use the tags you need to list the available tags and checkout a specific tag with the following commands:
+To build Gitea from source at a specific tagged release (like v1.0.0), list the available
+tags and check out the specific tag.
+
+List available tags with the following.
 
 ```
 git tag -l
-git checkout v1.0.0
-git checkout pr-xyz
+git checkout v1.0.0  # or git checkout pr-xyz
 ```
 
 ## Build
 
-Since we already bundle all required libraries to build Gitea you can continue with the build process itself. We provide various [make tasks](https://github.com/go-gitea/gitea/blob/master/Makefile) to keep the build process as simple as possible. <a href='{{< relref "doc/advanced/make.en-us.md" >}}'>See here how to get Make</a>. Depending on your requirements you possibly want to add various build tags, you can choose between these tags:
+Since all required libraries are already bundled in the Gitea source, it's
+possible to build Gitea with no additional downloads. Various
+[make tasks](https://github.com/go-gitea/gitea/blob/master/Makefile) are
+provided to keep the build process as simple as possible.
+<a href='{{< relref "doc/advanced/make.en-us.md" >}}'>See here how to get Make</a>.
+Depending on requirements, the following build tags can be included.
 
-* `bindata`: With this tag you can embed all assets required to run an instance of Gitea, this makes a deployment quite easy because you don't need to care about any additional file.
-* `sqlite`: With this tag you can enable support for a [SQLite3](https://sqlite.org/) database, this is only suggested for tiny Gitea installations.
-* `tidb`: With this tag you can enable support for a [TiDB](https://github.com/pingcap/tidb) database, it's a quite simple file-based database comparable with SQLite.
-* `pam`: With this tag you can enable support for PAM (Linux Pluggable Authentication Modules), this is useful if your users should be authenticated via your available system users.
+* `bindata`: Build a single monolithic binary, with all assets included.
+* `sqlite`: Enable support for a [SQLite3](https://sqlite.org/) database. Suggested only
+  for tiny installations.
+* `tidb`: Enable support for a [TiDB](https://github.com/pingcap/tidb) database.
+* `pam`: Enable support for PAM (Linux Pluggable Authentication Modules). Can be used to
+  authenticate local users or extend authentication to methods available to PAM.
 
-Now it's time to build the binary, we suggest to embed the assets with the `bindata` build tag, to include the assets you also have to execute the `generate` make task, otherwise the assets are not prepared to get embedded:
+Bundling assets into the binary using the `bindata` build tag can make development and
+testing easier, but is not ideal for a production deployment. To include assets, they
+must be built separately using the `generate` make task.
 
 ```
 TAGS="bindata" make generate build
@@ -68,12 +82,10 @@ TAGS="bindata" make generate build
 
 ## Test
 
-After following the steps above you will have a `gitea` binary within your working directory, first you can test it if it works like expected and afterwards you can copy it to the destination where you want to store it. When you launch Gitea manually from your CLI you can always kill it by hitting `Ctrl + C`.
+After following the steps above a `gitea` binary will be available in the working directory.
+It can be tested from this directory or moved to a directory with test data. When Gitea is
+launched manually from command line, it can be killed by pressing `Ctrl + C`.
 
 ```
 ./gitea web
 ```
-
-## Anything missing?
-
-Are we missing anything on this page? Then feel free to reach out to us on our [Discord server](https://discord.gg/NsatcWJ), there you will get answers to any question pretty fast.
diff --git a/docs/content/doc/installation/from-source.fr-fr.md b/docs/content/doc/installation/from-source.fr-fr.md
index 7e4078484d..7e4078484d 100755..100644
--- a/docs/content/doc/installation/from-source.fr-fr.md
+++ b/docs/content/doc/installation/from-source.fr-fr.md
diff --git a/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md b/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md
index 3d58167bf2..e004e3a0d3 100644
--- a/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md
+++ b/docs/content/doc/installation/run-as-service-in-ubuntu.en-us.md
@@ -13,56 +13,55 @@ menu:
     identifier: "linux-service"
 ---
 
-### Run as service in Ubuntu 16.04 LTS  
- 
-#### Using systemd  
+### Run as service in Ubuntu 16.04 LTS
 
-Run below command in terminal:  
+#### Using systemd
+
+Run the below command in a terminal:
 ```
 sudo vim /etc/systemd/system/gitea.service
-```  
+```
 
-Add code to the file from [here](https://github.com/go-gitea/gitea/blob/master/contrib/systemd/gitea.service).  
+Copy the sample [gitea.service](https://github.com/go-gitea/gitea/blob/master/contrib/systemd/gitea.service).
 
-Uncomment any service need to be enabled like mysql in this case in Unit section.  
+Uncomment any service that needs to be enabled on this host, such as MySQL.
 
-Change the user(git) accordingly to yours. And /home/git too if your username is different than git. Change the PORT or remove the -p flag if default port is used.  
+Change the user, home directory, and other required startup values. Change the
+PORT or remove the -p flag if default port is used.
 
-Lastly start and enable gitea at boot:  
+Enable and start gitea at boot:
 ```
+sudo systemctl enable gitea
 sudo systemctl start gitea
-```  
 ```
-sudo systemctl enable gitea
-```  
 
 
-#### Using supervisor  
+#### Using supervisor
 
-Install supervisor by running below command in terminal:  
+Install supervisor by running below command in terminal:
 ```
 sudo apt install supervisor
-```  
+```
 
-Create a log dir for the supervisor logs(assuming gitea is installed in /home/git/gitea/):  
+Create a log dir for the supervisor logs:
 ```
+# assuming gitea is installed in /home/git/gitea/
 mkdir /home/git/gitea/log/supervisor
-```  
+```
 
-Open supervisor config file in vi/vim/nano etc.  
+Open supervisor config file in a file editor:
 ```
 sudo vim /etc/supervisor/supervisord.conf
-```  
+```
 
-And append the code at the end of the file from [here](https://github.com/go-gitea/gitea/blob/master/contrib/supervisor/gitea).  
+Append the configuration from the sample
+[supervisord config](https://github.com/go-gitea/gitea/blob/master/contrib/supervisor/gitea).
 
-Change the user(git) accordingly to yours. And /home/git too if your username is different than git. Change the PORT or remove the -p flag if default port is used.  
+Change the user(git) and home(/home/git) settings to match the deployment
+environment. Change the PORT or remove the -p flag if default port is used.
 
-Lastly start and enable supervisor at boot:  
+Lastly enable and start supervisor at boot:
 ```
+sudo systemctl enable supervisor
 sudo systemctl start supervisor
-```  
 ```
-sudo systemctl enable supervisor
-```  
-
diff --git a/docs/content/doc/installation/windows-service.en-us.md b/docs/content/doc/installation/windows-service.en-us.md
index 0092c261c7..4955204d06 100644
--- a/docs/content/doc/installation/windows-service.en-us.md
+++ b/docs/content/doc/installation/windows-service.en-us.md
@@ -15,19 +15,22 @@ menu:
 
 # Register as a Windows Service
 
-To register Gitea as a Windows service, first run `cmd` as an Administrator, and then run the following command:
+To register Gitea as a Windows service, open a command prompt (cmd) as an Administrator,
+then run the following command:
 
 ```
 sc create gitea start= auto binPath= ""C:\gitea\gitea.exe" web --config "C:\gitea\custom\conf\app.ini""
 ```
 
-Do not forget to replace `C:\gitea` with your real Gitea folder.
+Do not forget to replace `C:\gitea` with the correct Gitea directory.
 
-After, open "Windows Services", search for the service named "gitea", right-click it and click on "Run". If everything is OK you should be able to reach Gitea on `http://localhost:3000` (or the port is was configured, if different than 3000).
+Open "Windows Services", search for the service named "gitea", right-click it and click on
+"Run". If everything is OK Gitea will be reachable on `http://localhost:3000` (or the port
+that was configured).
 
 ## Unregister as a service
 
-To unregister Gitea as a service, open `cmd` as an Administrator and run:
+To unregister Gitea as a service, open a command prompt (cmd) as an Administrator and run:
 
 ```
 sc delete gitea
diff --git a/docs/content/doc/installation/windows-service.fr-fr.md b/docs/content/doc/installation/windows-service.fr-fr.md
index 66cc5fc6dd..66cc5fc6dd 100755..100644
--- a/docs/content/doc/installation/windows-service.fr-fr.md
+++ b/docs/content/doc/installation/windows-service.fr-fr.md
diff --git a/docs/content/doc/installation/with-docker.en-us.md b/docs/content/doc/installation/with-docker.en-us.md
index c41c93288d..c476391481 100644
--- a/docs/content/doc/installation/with-docker.en-us.md
+++ b/docs/content/doc/installation/with-docker.en-us.md
@@ -15,13 +15,19 @@ menu:
 
 # Installation with Docker
 
-We provide automatically updated Docker images within our Docker Hub organization. It is up to you and your deployment to always use the latest stable tag or to use another service that updates the Docker image for you.
+Gitea provides automatically updated Docker images within its Docker Hub organization. It is
+possible to always use the latest stable tag or to use another service that handles updating
+Docker images.
 
-This reference setup guides you through the setup based on `docker-compose`, the installation of `docker-compose` is out of scope of this documentation. To install `docker-compose` follow the official [install instructions](https://docs.docker.com/compose/install/).
+This reference setup guides users through the setup based on `docker-compose`, the installation
+of `docker-compose` is out of scope of this documentation. To install `docker-compose` follow
+the official [install instructions](https://docs.docker.com/compose/install/).
 
 ## Basics
 
-The most simple setup just creates a volume and a network and starts the `gitea/gitea:latest` image as a service. Since there is no database available you can start it only with SQLite3. Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
+The most simple setup just creates a volume and a network and starts the `gitea/gitea:latest`
+image as a service. Since there is no database available one can be initialized using SQLite3.
+Create a directory like `gitea` and paste the following content into a file named `docker-compose.yml`.
 
 ```yaml
 version: "2"
@@ -45,7 +51,9 @@ services:
 
 ## Custom port
 
-To bind the integrated openSSH daemon and the webserver on a different port, you just need to adjust the port section. It's common to just change the host port and keep the ports within the container like they are.
+To bind the integrated openSSH daemon and the webserver on a different port, adjust
+the port section. It's common to just change the host port and keep the ports within
+the container like they are.
 
 ```diff
 version: "2"
@@ -71,7 +79,8 @@ services:
 
 ## MySQL database
 
-To start Gitea in combination with a MySQL database you should apply these changes to the `docker-compose.yml` file created above.
+To start Gitea in combination with a MySQL database, apply these changes to the
+`docker-compose.yml` file created above.
 
 ```diff
 version: "2"
@@ -110,7 +119,8 @@ services:
 
 ## PostgreSQL database
 
-To start Gitea in combination with a PostgreSQL database you should apply these changes to the `docker-compose.yml` file created above.
+To start Gitea in combination with a PostgreSQL database, apply these changes to
+the `docker-compose.yml` file created above.
 
 ```diff
 version: "2"
@@ -148,7 +158,9 @@ services:
 
 ## Named volumes
 
-To use named volumes instead of host volumes you just have to define and use the named volume within the `docker-compose.yml` configuration. This change will automatically create the required volume.
+To use named volumes instead of host volumes, define and use the named volume
+within the `docker-compose.yml` configuration. This change will automatically
+create the required volume.
 
 ```diff
 version: "2"
@@ -175,24 +187,31 @@ services:
       - "222:22"
 ```
 
-If you are using MySQL or PostgreSQL it's up to you to create named volumes for these containers as well.
+MySQL or PostgreSQL containers will need to be created separately.
 
 ## Start
 
-To start this setup based on `docker-compose` you just have to execute `docker-compose up -d` to launch Gitea in the background. You can see if it started properly via `docker-compose ps`, and you can tail the log output via `docker-compose logs`.
+To start this setup based on `docker-compose`, execute `docker-compose up -d`,
+to launch Gitea in the background. Using `docker-compose ps` will show if Gitea
+started properly. Logs can be viewed with `docker-compose logs`.
 
-If you want to shutdown the setup again just execute `docker-compose down`, this will stop and kill the containers, the volumes will still exist.
+To shut down the setup, execute `docker-compose down`. This will stop
+and kill the containers. The volumes will still exist.
 
-Notice: if you use a non 3000 port on http, you need change app.ini `LOCAL_ROOT_URL  = http://localhost:3000/`.
+Notice: if using a non-3000 port on http, change app.ini to match
+`LOCAL_ROOT_URL = http://localhost:3000/`.
 
 ## Install
 
-After starting the Docker setup via `docker-compose` you should access Gitea with your favorite browser to finalize the installation. Please visit http://server-ip:3000 and follow the installation wizard. If you have started a database with the `docker-compose` setup as documented above please note that you have to use `db` as the database hostname.
+After starting the Docker setup via `docker-compose` Gitea should be available using a
+favorite browser to finalize the installation. Visit http://server-ip:3000 and follow the
+installation wizard. If the database was started with the `docker-compose` setup as
+documented above please note that `db` must be used as the database hostname.
 
 # Customization
 
-Customization files described [here](https://docs.gitea.io/en-us/customizing-gitea/) should be placed in `/data/gitea` directory. If you are using host volumes it's quite easy to access these files, for named volumes you have to do it through another container or you should directly access `/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at `/data/gitea/conf/app.ini` after the installation.
-
-# Anything missing?
-
-Are we missing anything on this page? Then feel free to reach out to us on our [Discord server](https://discord.gg/NsatcWJ), there you will get answers to any question pretty fast.
+Customization files described [here](https://docs.gitea.io/en-us/customizing-gitea/) should
+be placed in `/data/gitea` directory. If using host volumes it's quite easy to access these
+files; for named volumes this is done through another container or by direct access at
+`/var/lib/docker/volumes/gitea_gitea/_data`. The configuration file will be saved at
+`/data/gitea/conf/app.ini` after the installation.
diff --git a/docs/content/doc/installation/with-docker.fr-fr.md b/docs/content/doc/installation/with-docker.fr-fr.md
index 2f3567ee62..2f3567ee62 100755..100644
--- a/docs/content/doc/installation/with-docker.fr-fr.md
+++ b/docs/content/doc/installation/with-docker.fr-fr.md