Documentation improvements

Author: andreynering

README.md

@@ -1,10 +1,9 @@
 [![Build Status](https://travis-ci.org/go-task/task.svg?branch=master)](https://travis-ci.org/go-task/task)
 
-# Task - A task runner / simpler Make alternative written in Go
+# Task
 
-Task is a simple tool that allows you to easily run development and build
-tasks. Task is written in Go, but can be used to develop any language.
-It aims to be simpler and easier to use then [GNU Make][make].
+Task is a task runner / build tool that aims to be simpler and easier to use
+than, for example, [GNU Make][make].
 
 ---
 

docs/README.md

@@ -1,9 +1,46 @@
 # Task
 
-A task runner / simpler Make alternative written in Go
+Task is a task runner / build tool that aims to be simpler and easier to use
+than, for example, [GNU Make][make].
 
-Task is a simple tool that allows you to easily run development and build
-tasks. Task is written in Go, but can be used to develop any language.
-It aims to be simpler and easier to use then [GNU Make][make].
+Since it's written in [Go][go], Task is just a single binary and has no other
+dependencies, which means you don't need to mess with any complicated install
+setups just to use a build tool.
+
+Once [installed](installation), you just need to describe your build tasks
+using a simple [YAML][yaml] schema in a file called `Taskfile.yml`:
+
+```yaml
+version: '2'
+
+tasks:
+  hello:
+    cmds:
+      - echo 'Hello World from Task!'
+    silent: true
+```
+
+And call it by running `task hello` from you terminal.
+
+The above example is just the start, you can take a look at the [usage](usage)
+guide to check the full schema documentation and Task features.
+
+## Features
+
+- [Easy installation](installation): just download a single binary, add to
+  $PATH and you're done! Or you can also install using [Homebrew][homebrew] or
+  [Snapcraft][snapcraft] if you want;
+- Available on CIs: by adding [this simple command](installation#install-script)
+  to install on your CI script and you're done to use Task as part of your CI pipeline;
+- Truly cross-platform: while most build tools only work well on Linux or macOS,
+  Task also supports Windows thanks to [this awesome shell interpreter for Go][sh];
+- Great for code generation: you can easily [prevent a task from running](usage#prevent-unnecessary-work)
+  if a given set of files haven't changed since last run (based either on its
+  timestamp or content).
 
 [make]: https://www.gnu.org/software/make/
+[go]: https://golang.org/
+[yaml]: http://yaml.org/
+[homebrew]: https://brew.sh/
+[snapcraft]: https://snapcraft.io/
+[sh]: https://mvdan.cc/sh

docs/installation.md

@@ -1,12 +1,10 @@
 # Installation
 
-## Go
-
-If you have a [Golang][golang] environment setup, you can simply run:
+## Binary
 
-```bash
-go get -u -v github.com/go-task/task/cmd/task
-```
+Or you can download the binary from the [releases][releases] page and add to
+your $PATH. DEB and RPM packages are also available.
+The `task_checksums.txt` file contains the sha256 checksum for each file.
 
 ## Homebrew
 
@@ -27,23 +25,27 @@ right:
 sudo snap install task
 ```
 
+## Go
+
+If you have a [Go][go] environment setup, you can simply run:
+
+```bash
+go get -u -v github.com/go-task/task/cmd/task
+```
+
 ## Install script
 
 We also have a [install script][installscript], which is very useful on
-scanarios like CIs. Many thanks to [godownloader][godownloader] for easily
-generating this script.
+scanarios like CIs. Many thanks to [godownloader][godownloader] for allowing
+easily generating this script.
 
 ```bash
 curl -s https://taskfile.org/install.sh | sh
 ```
 
-## Binary
-
-Or you can download the binary from the [releases][releases] page and add to
-your `PATH`. DEB and RPM packages are also available.
-The `task_checksums.txt` file contains the sha256 checksum for each file.
+> This method will download the binary on the local `./bin` directory by default.
 
-[golang]: https://golang.org/
+[go]: https://golang.org/
 [snapcraft]: https://snapcraft.io/
 [homebrew]: https://brew.sh/
 [installscript]: https://github.com/go-task/task/blob/master/install-task.sh