Overhaul README and docs improvements

Signed-off-by: Khosrow Moossavi <khos2ow@gmail.com>

docs/developer-guide/plugins.md

@@ -16,5 +16,5 @@ If you want to create a new plugin, please refer to [tfdocs-format-template]. Th
 plugin can use [plugin-sdk] to communicate with the host process. You can create a
 new repository from `Use this template`.
 
-[tfdocs-format-template]: https://github.com/terraform-docs/tfdocs-format-template
 [plugin-sdk]: https://github.com/terraform-docs/plugin-sdk
+[tfdocs-format-template]: https://github.com/terraform-docs/tfdocs-format-template

docs/how-to/pre-commit-hooks.md

@@ -80,5 +80,5 @@ This is very basic and higly simplified version of [pre-commit-terraform](https:
 Please refer to it for complete examples and guides.
 {{< /alert >}}
 
-[`pre-commit`]: https://pre-commit.com/
 [git hooks]: https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks
+[`pre-commit`]: https://pre-commit.com/

docs/user-guide/configuration.md

@@ -42,13 +42,12 @@ $ tree
 $ terraform-docs -c .tfdocs-config.yml .
 ```
 
-As of `v0.13.0`, the order for looking for config file is *(2 and 4 were added
-in `v0.15.0`)*:
+As of `v0.13.0`, the order for looking for config file is:
 
 1. root of module directory
-1. `.config/` folder at root of module directory
+1. `.config/` folder at root of module directory <sup class="no-top">(since v0.15.0)</sup>
 1. current directory
-1. `.config/` folder at current directory
+1. `.config/` folder at current directory <sup class="no-top">(since v0.15.0)</sup>
 1. `$HOME/.tfdocs.d/`
 
 if `.terraform-docs.yml` is found in any of the folders above, that will take
@@ -66,9 +65,9 @@ Below is a complete list of options that can be used with `terraform-docs`, with
 default values.
 
 ```yaml
-version: ""
+formatter: "" # this is required
 
-formatter: <FORMATTER_NAME>
+version: ""
 
 header-from: main.tf
 footer-from: ""
@@ -114,7 +113,7 @@ settings:
 ```
 
 {{< alert type="info" >}}
-Only `formatter` is required, the rest of the options are optional.
+`formatter` is the only required option.
 {{< /alert >}}
 
 ## Usage

docs/user-guide/configuration/content.md

@@ -35,7 +35,7 @@ and following functions:
 
 These variables are the generated output of individual sections in the selected
 formatter. For example `{{ .Inputs }}` is Markdown Table representation of _inputs_
-when formatter is set to `markdown table` and so on.
+when formatter is set to `markdown table`.
 
 {{< alert type="info" >}}
 Sections visibility (i.e. `sections.show` and `sections.hide`) takes

docs/user-guide/installation.md

@@ -47,10 +47,18 @@ choco install terraform-docs
 
 ## Docker
 
-You also can run `terraform-docs` as a container:
+terraform-docs can be run as a container by mounting a directory with `.tf`
+files in it and run the following command:
 
 ```bash
-docker run quay.io/terraform-docs/terraform-docs:0.15.0
+docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.15.0 markdown /terraform-docs
+```
+
+If `output.file` is not enabled for this module, generated output can be redirected
+back to a file:
+
+```bash
+docker run --rm --volume "$(pwd):/terraform-docs" -u $(id -u) quay.io/terraform-docs/terraform-docs:0.15.0 markdown /terraform-docs > doc.md
 ```
 
 {{< alert type="primary" >}}
@@ -77,9 +85,15 @@ Windows releases are in `ZIP` format.
 
 ## Go Users
 
-The latest version can be installed using `go get`:
+The latest version can be installed using `go install` or `go get`:
 
 ```bash
+# go1.17+
+go install github.com/terraform-docs/terraform-docs@v0.15.0
+```
+
+```bash
+# go1.16
 GO111MODULE="on" go get github.com/terraform-docs/terraform-docs@v0.15.0
 ```
 
@@ -94,7 +108,7 @@ GO111MODULE="on" go get github.com/segmentio/terraform-docs@v0.9.1
 ```
 
 {{< alert type="primary" >}}
-Please use the latest Go to do this, minimum `go1.16` or greater.
+Please use the latest Go to do this, minimum `go1.16` is required.
 {{< /alert >}}
 
 This will put `terraform-docs` in `$(go env GOPATH)/bin`. If you encounter the error
@@ -131,7 +145,7 @@ autoload -U compinit && compinit
 
 To make this change permanent, the above commands can be added to `~/.profile` file.
 
-[Release]: https://github.com/terraform-docs/terraform-docs/releases
-[Homebrew]: https://brew.sh
-[Scoop]: https://scoop.sh/
 [Chocolatey]: https://www.chocolatey.org
+[Homebrew]: https://brew.sh
+[Release]: https://github.com/terraform-docs/terraform-docs/releases
+[Scoop]: https://scoop.sh/

docs/user-guide/introduction.md

@@ -66,5 +66,5 @@ terraform-docs compatiblity matrix with Terraform can be found below:
 </table>
 
 [configuration]: {{< ref "configuration" >}}
-[markdown table]: {{< ref "markdown-table" >}}
 [formats]: {{< ref "terraform-docs" >}}
+[markdown table]: {{< ref "markdown-table" >}}