General documentation cleanup (gogs#3317)

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

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`.
+Place custom files in corresponding sub-folder under `custom/options`.

docs/content/doc/advanced/hacking-on-gitea.en-us.md

@@ -15,28 +15,41 @@ 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
 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.

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`

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
-

docs/content/doc/features/authentication.en-us.md

@@ -78,7 +78,7 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields:
 
 - Bind Password (optional)
   - The password for the Bind DN specified above, if any. _Note: The password
-    is stored in plaintext at the server. As such, ensure that your Bind DN
+    is stored in plaintext at the server. As such, ensure that the Bind DN
     has as few privileges as possible._
 
 - User Search Base **(required)**
@@ -110,7 +110,8 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields:
 **LDAP using simple auth** adds the following fields:
 
 - User DN **(required)**
-  - A template to use as the user's DN. The `%s` matching parameter will be substituted with login name given on sign-in form.
+  - A template to use as the user's DN. The `%s` matching parameter will be
+    substituted with login name given on sign-in form.
   - Example: `cn=%s,ou=Users,dc=mydomain,dc=com`
   - Example: `uid=%s,ou=Users,dc=mydomain,dc=com`
 
@@ -141,18 +142,20 @@ Both the LDAP via BindDN and the simple auth LDAP share the following fields:
 
 ## PAM (Pluggable Authentication Module)
 
-To configure this you just need to set the 'PAM Service Name' to a filename in `/etc/pam.d/`.
-If you want it to work with normal Linux passwords, the user running Gitea must have read access to `/etc/shadow`.
+To configure PAM, set the 'PAM Service Name' to a filename in `/etc/pam.d/`. To
+work with normal Linux passwords, the user running Gitea must have read access
+to `/etc/shadow`.
 
 ## SMTP (Simple Mail Transfer Protocol)
 
-This option allows Gitea to log in to your SMTP host as a Gitea user. To configure this, simply set the fields below:
+This option allows Gitea to log in to an SMTP host as a Gitea user. To
+configure this, set the fields below:
 
 - Authentication Name **(required)**
   - A name to assign to the new method of authorization.
 
 - SMTP Authentication Type **(required)**
-  - Type of authentication for use on your SMTP host, PLAIN or LOGIN.
+  - Type of authentication to use to connect to SMTP host, PLAIN or LOGIN.
 
 - Host **(required)**
   - The address where the SMTP host can be reached.
@@ -163,23 +166,26 @@ This option allows Gitea to log in to your SMTP host as a Gitea user. To configu
   - Example: `587`
 
 - Allowed Domains
-  - Restrict what domains can log in if you're using public SMTP host or SMTP host with multiple domains.
+  - Restrict what domains can log in if using a public SMTP host or SMTP host
+    with multiple domains.
   - Example: `gitea.io,mydomain.com,mydomain2.com`
 
 - Enable TLS Encryption
   - Enable TLS encryption on authentication.
 
 - Skip TLS Verify
   - Disable TLS verify on authentication.
-  
+
 - This authentication is activate
   - Enable or disable this auth.
 
 ## FreeIPA
 
-- In order to log in to Gitea using FreeIPA credentials, you need to create a bind account for Gitea to use:
+- In order to log in to Gitea using FreeIPA credentials,a bind account needs to
+  be created for Gitea:
 
--  On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com` with your DN, and providing an appropriately secure password:
+- On the FreeIPA server, create a `gitea.ldif` file, replacing `dc=example,dc=com`
+  with your DN, and provide an appropriately secure password:
 ```
   dn: uid=gitea,cn=sysaccounts,cn=etc,dc=example,dc=com
   changetype: add
@@ -191,15 +197,18 @@ This option allows Gitea to log in to your SMTP host as a Gitea user. To configu
   nsIdleTimeout: 0
 ```
 
-- Import the LDIF (change localhost to an IPA server if needed), you’ll be prompted for your Directory Manager password:
+- Import the LDIF (change localhost to an IPA server if needed). A prompt for
+ Directory Manager password will be presented:
 ```
   ldapmodify -h localhost -p 389 -x -D \
   "cn=Directory Manager" -W -f gitea.ldif
 ```
--  Add an IPA group for gitea_users :
+- Add an IPA group for gitea\_users :
 ```
   ipa group-add --desc="Gitea Users" gitea_users
 ```
--  Note: If you get an error about IPA credentials, please run `kinit admin` and give your admin account password.
+- Note: For errors about IPA credentials, run `kinit admin` and provide the
+  domain admin account password.
 
--  Now login to the Gitea as an Administrator, click on "Authentication" under Admin Panel. Then click `Add New Source` and fill in the details, changing all where appropriate to your own domain.
+- Log in to Gitea as an Administrator and click on "Authentication" under Admin Panel.
+  Then click `Add New Source` and fill in the details, changing all where appropriate.

docs/content/doc/features/webhooks.en-us.md

@@ -15,11 +15,14 @@ menu:
 
 # Webhooks
 
-Gitea supports web hooks for repository events, you can find it in settings page(`/:username/:reponame/settings/hooks`). All event pushes are POST requests, and we currently support two formats: Gitea and Slack.
+Gitea supports web hooks for repository events, this can be found in the settings
+page(`/:username/:reponame/settings/hooks`). All event pushes are POST requests.
+The two methods currently supported are Gitea and Slack.
 
 ### Event information
 
-Following shows an example of event information that will be sent by Gitea to Payload URL:
+The following is an example of event information that will be sent by Gitea to
+a Payload URL:
 
 
 ```

docs/content/doc/help.en-us.md

@@ -0,0 +1,13 @@
+---
+date: "2017-01-20T15:00:00+08:00"
+title: "Help"
+slug: "help"
+weight: 50
+toc: false
+draft: false
+menu:
+  sidebar:
+    name: "Help"
+    weight: 50
+    identifier: "help"
+---

docs/content/doc/help/seek-help.en-us.md

@@ -0,0 +1,28 @@
+---
+date: "2017-01-20T15:00:00+08:00"
+title: "Support Options"
+slug: "seek-help"
+weight: 10
+toc: true
+draft: false
+menu:
+  sidebar:
+    parent: "help"
+    name: "Support Options"
+    weight: 20
+    identifier: "seek-help"
+---
+
+# Support Options
+
+- [Discord](https://discord.gg/NsatcWJ)
+- [#gitea on Freenode](http://webchat.freenode.net?nick=giteachat....&channels=%23gitea&prompt=1)
+- [Matrix](https://matrix.to/#/#gitea-dev:matrix.org)
+
+## Bugs
+
+If you found a bug, please create an [issue on Github](https://github.com/go-gitea/gitea/issues).
+
+## Chinese Support
+
+Support for the Chinese language is provided at [gocn.io](https://gocn.io/topic/Gitea).