Update documentation and add a index

If one wanted to read all the documentation in the Gitaly repository the
best way to do so was opening the doc directory. Structure was missing.
This commit updates the documentation and adds an index page.

4 files changed, 63 insertions, 39 deletions

diff --git a/README.md b/README.md
index ecfb1ebc8..3e6609ae7 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,11 @@
 # ![Gitaly](https://gitlab.com/gitlab-org/gitaly/uploads/509123ed56bd51247996038c858db006/gitaly-wordmark-small.png)
 
-[![Pipeline status](https://gitlab.com/gitlab-org/gitaly/badges/master/pipeline.svg)](https://gitlab.com/gitlab-org/gitaly/commits/master) [![coverage report](https://gitlab.com/gitlab-org/gitaly/badges/master/coverage.svg)](https://codecov.io/gl/gitlab-org/gitaly)
-
 **Quick Links**:
-  [**Roadmap**](https://gitlab.com/groups/gitlab-org/-/roadmap?label_name%5B%5D=Gitaly&scope=all&sort=start_date_asc&state=opened) |
+  [**Roadmap**][roadmap] |
   [Want to Contribute?](https://gitlab.com/gitlab-org/gitaly/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=Accepting%20merge%20requests) |
   [GitLab Gitaly Issues](https://gitlab.com/groups/gitlab-org/-/issues?scope=all&state=opened&utf8=%E2%9C%93&label_name%5B%5D=Gitaly) |
   [GitLab Gitaly Merge Requests](https://gitlab.com/groups/gitlab-org/-/merge_requests?label_name%5B%5D=Gitaly) |
-  [gitlab.com monitoring dashboard](https://dashboards.gitlab.com/d/000000176/gitaly) |
+  [GitLab.com Monitoring Dashboard][dashboards]
 
 --------------------------------------------
 
@@ -33,17 +31,16 @@ longer uses direct disk access to touch Git repositories; the [NFS
 mounts have been
 removed](https://about.gitlab.com/2018/09/12/the-road-to-gitaly-1-0/).
 
-The last feature that remains to be migrated is the [Elasticsearch
-indexer](https://gitlab.com/gitlab-org/gitaly/issues/760). Once that is
-done we can conclude the migration project by [removing the Git
-repository storage paths from gitlab-rails's
+For performance reasons some RPCs can be performed through NFS still. An
+effort is made to mitigate performance issues by removing [Gitaly N+1](https://gitlab.com/groups/gitlab-org/-/epics/827).
+Once that is no longer neccesairy we can conclude the migration project by 
+[removing the Git repository storage paths from gitlab-rails's
 configuration](https://gitlab.com/gitlab-org/gitaly/issues/1282).
 
-In the meantime we are building features according to our
-[roadmap](https://gitlab.com/groups/gitlab-org/-/roadmap?label_name%5B%5D=Gitaly&scope=all&sort=start_date_asc&state=opened).
+In the meantime we are building features according to our [roadmap][roadmap].
 
 If you're interested in seeing how well Gitaly is performing on
-GitLab.com, we have dashboards!
+GitLab.com, we have [dashboards][dashboards]!
 
 ##### Overall
 
@@ -111,6 +108,10 @@ use library code from the
 [gitlab.com/gitlab-org/gitaly/client](https://gitlab.com/gitlab-org/gitaly/tree/master/client)
 package.
 
+## Further reading
+
+More about the project, and its processes is [accumulated in the docs](doc/index.md).
+
 ## Distributed Tracing
 
 Gitaly supports distributed tracing through [LabKit](https://gitlab.com/gitlab-org/labkit/) using [OpenTracing APIs](https://opentracing.io).
@@ -137,3 +138,6 @@ GITLAB_TRACING=opentracing://jaeger ./gitaly config.toml
 - [Infrastructure Team Update 2017-05-11](https://about.gitlab.com/2017/05/11/functional-group-updates/#infrastructure-team)
 - [Gitaly Basics, 2017-05-01](https://docs.google.com/presentation/d/1cLslUbXVkniOaeJ-r3s5AYF0kQep8VeNfvs0XSGrpA0/edit#slide=id.g1c73db867d_0_0)
 - [Git Paris meetup, 2017-02-22](https://docs.google.com/presentation/d/19OZUalFMIDM8WujXrrIyCuVb_oVeaUzpb-UdGThOvAo/edit?usp=sharing) a high-level overview of what our plans are and where we are.
+
+[dashboards]: https://dashboards.gitlab.com/d/000000176/gitaly
+[roadmap]: https://gitlab.com/groups/gitlab-org/-/roadmap?label_name%5B%5D=Gitaly&scope=all&sort=start_date_asc&state=opened
diff --git a/doc/PROCESS.md b/doc/PROCESS.md
index ebf866c3c..b68bc7a68 100644
--- a/doc/PROCESS.md
+++ b/doc/PROCESS.md
@@ -1,14 +1,10 @@
-## Plan
-
-We use our issues board for keeping our work in progress up to date in a single place. Please refer to it to see the current status of the project.
-
 ## Gitaly Team Process
 
 ### Gitaly Releases
 
 Gitaly uses [SemVer](https://semver.org) version numbering.
 
-## Branching Model
+#### Branching Model
 
 All `vX.Y.0` tags get created on the `master` branch. We only make patch
 releases when targeting a GitLab stable branch. Patch releases
@@ -19,3 +15,27 @@ There should be **no patch releases on `master`**. Gitaly patch releases should
 only be used for GitLab stable branches. If the release is not for a
 GitLab stable branch, just increment the minor (or major) version
 counter.
+
+#### Creating a release
+
+- Pick a release number (x.y.z)
+- Check out the master branch on your local machine
+- run `_support/release x.y.z`
+
+Where x.y.z is a semver-compliant version number.
+
+- To automatically create a merge-request in Gitlab CE to update that
+  project to the latest tag, run
+
+```shell
+GITLAB_TOKEN=$(cat /path/to/gitlab-token) _support/update-downstream-server-version
+```
+
+- This will create a merge-request (with changelog) and assign it to you. Once the build has
+  completed successfully, assign it to a maintainer for review.
+
+## Experimental builds
+
+Push the release tag to dev.gitlab.org/gitlab/gitaly. After the
+passing the test suite, the tag will automatically be built and
+published in https://packages.gitlab.com/gitlab/unstable.
diff --git a/doc/README.md b/doc/README.md
new file mode 100644
index 000000000..8a56249f0
--- /dev/null
+++ b/doc/README.md
@@ -0,0 +1,23 @@
+## Gitaly documentation
+
+The historical reasons for the inception of Gitaly and our design decisions are
+written in [the design doc](doc/DESIGN.md).
+
+#### Configuring Gitaly
+
+Running Gitaly requires it to be configured correctly, options are described in
+the [configuration documentation](doc/configuration/README.md).
+
+#### Developing Gitaly
+
+- When new to Gitaly development, start by reading the [beginners guide](docs/beginners_guid.md).
+- When developing on Gitaly-Ruby, read the [Gitaly-Ruby doc](doc/ruby_endpoint.md)
+- The Gitaly release process is descripted in [our process doc](doc/PROCESS.md)
+- Tests use Git repositories too, [read more about them](doc/test_repos.md)
+
+#### Gitaly HA
+
+Gitaly does not replicate any data. If a Gitaly server goes down, any of its
+clients can't read or write to the repositories stored on that server. This
+means that Gitaly is not highly available. How this will be solved is described
+[in the HA design document](doc/design_ha.md)
diff --git a/doc/release.md b/doc/release.md
deleted file mode 100644
index 7986d21cf..000000000
--- a/doc/release.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Gitaly release process
-
-- Pick a release number (x.y.z)
-- Check out the master branch on your local machine
-- run `_support/release x.y.z`
-
-Where x.y.z is a semver-compliant version number.
-
-- To automatically create a merge-request in Gitlab CE to update that
-  project to the latest tag, run
-
-```shell
-GITLAB_TOKEN=$(cat /path/to/gitlab-token) _support/update-downstream-server-version
-```
-
-- This will create a merge-request (with changelog) and assign it to you. Once the build has
-  completed successfully, assign it to a maintainer for review.
-
-## Experimental builds
-
-Push the release tag to dev.gitlab.org/gitlab/gitaly. After the
-passing the test suite, the tag will automatically be built and
-published in https://packages.gitlab.com/gitlab/unstable.