Add documentation

Signed-off-by: Sascha Grunert <sgrunert@suse.com>

README.md

@@ -8,8 +8,73 @@
 Welcome to performabot! This little helper can be used to provide Continuous
 Performance Reports within your GitHub project.
 
+**Currently only [golang ginkgo](https://onsi.github.io/ginkgo/#benchmark-tests)
+performance benchmarks supported.**
+
 ## How it works
 
+Performabot parses the output of a micro-benchmarking framework. After the
+successful parsing it puts the data into a local
+[SQLite](https://www.sqlite.org) database. This database is named
+`performabot.sqlite`, where multiple consecutive test runs will result in
+reusing that database. If Performabot finds data where it can compare the
+current run against, then it will do this as well.
+
+After the run Performabot updates the corresponding GitHub pull request with a
+comment which contains all necessary information, like these:
+
+```diff
+@@                  Performance Diff                    @@
+##                                        Ø       ±   × ##
+==========================================================
+  create PodSandbox                  0.404s  0.471s  20
+  PodSandbox status                  0.000s  0.000s  20
+  stop PodSandbox                    0.240s  0.015s  20
+  remove PodSandbox                  0.056s  0.012s  20
+  create PodSandbox and container    0.405s  0.049s  20
+  list Container                     0.002s  0.005s  20
+  pull Image                         6.498s  0.478s  20
+  Image status                       0.002s  0.001s  20
+  remove Image                       0.068s  0.044s  20
+  create Container                   0.122s  0.035s  20
+  start Container                    0.030s  0.012s  20
+  Container status                   0.002s  0.001s  20
+  stop Container                     0.048s  0.014s  20
+  remove Container                   0.026s  0.004s  20
+==========================================================
+- list PodSandbox                    0.000s  0.000s  20
++ list PodSandbox                    0.000s  0.000s  20
+=                                    0.000s  0.000s   0
+==========================================================
+- list Container                     0.002s  0.005s  20
++ list Container                     0.000s  0.000s  20
+=                                   -0.002s -0.005s   0
+==========================================================
+```
+
+The test name, its average and derivation times and the amount of runs for the
+test is visible inside the table. Beside this, the difference between two tests
+is listed as well if Performabot finds a base commit to compare against.
+
+Performabot needs some information about the local test environment before
+actually commenting to GitHub pull requests. These parameters can be specified
+either via local environment variables or the command line, where test runs
+within [CircleCI](https://circleci.com) should work out of the box, except for
+the token. The needed information are:
+
+| Flag                  | Environment Variable                        | Description                 |
+| --------------------- | ------------------------------------------- | --------------------------- |
+| `-c`, `--commit`      | `$PB_COMMIT`, `$CIRCLE_SHA1`                | Commit hash                 |
+| `-p`,`--pull-request` | `$PB_PULL_REQUEST`,`$CIRCLE_PR_NUMBER`      | Pull request number         |
+| `-r`, `--repository`  | `$PB_REPOSITORY`,`$CIRCLE_PROJECT_REPONAME` | GitHub repository name      |
+| `-o`, `--owner`       | `$PB_OWNER`,`$CIRCLE_PROJECT_USERNAME`      | GitHub repository owner     |
+| `-t`, `--token`       | `$PB_TOKEN`                                 | Personal access OAuth token |
+
+Personal access tokens can be generated [via the GitHub developer
+settings](https://github.com/settings/tokens), whereas only `public_repo`
+(Access public repositories) has to be activated in case of an open source
+project.
+
 ## Depdendencies
 
 There is only one dependency needed to get started with this project:
@@ -21,15 +86,18 @@ To build the project, simply run:
 > make
 ```
 
-If you need a shell where all build dependencies are already in `$PATH`, then
-run:
+The binary should be available at `result/bin//performabot` after successful
+compilation. If you need a shell where all build time dependencies are already
+included in `$PATH`, then run:
 
 ```shell
 > make shell
 ```
 
 There are other useful targets within the [Makefile](Makefile), which are used
-by the CI and could be worth a look.
+by the CI and could be worth a look. If you don't want to use nix, then you're
+free to build the project with [stack](https://haskellstack.org) or
+[cabal](https://www.haskell.org/cabal) as well.
 
 ## Contributing