From a1f9869eb2ae7f9d82a6e2fb50fed4340b6c040a Mon Sep 17 00:00:00 2001
From: Slavi Pantaleev <slavi@devture.com>
Date: Sun, 10 Mar 2019 17:02:17 +0200
Subject: [PATCH] Improve documentation about getting the playbook

---
 docs/README.md               |  4 +++-
 docs/configuring-playbook.md |  8 +++++--
 docs/getting-the-playbook.md | 41 ++++++++++++++++++++++++++++++++++++
 docs/prerequisites.md        |  2 +-
 4 files changed, 51 insertions(+), 4 deletions(-)
 create mode 100644 docs/getting-the-playbook.md

diff --git a/docs/README.md b/docs/README.md
index 35ba609a8..1718c6ace 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -4,7 +4,9 @@
 
 - [Configuring your DNS server](configuring-dns.md)
 
-- [Configuring this Ansible playbook](configuring-playbook.md)
+- [Getting this playbook's source code](getting-the-playbook.md)
+
+- [Configuring the playbook](configuring-playbook.md)
 
 - [Installing](installing.md)
 
diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md
index 3da733b24..4951d8d4e 100644
--- a/docs/configuring-playbook.md
+++ b/docs/configuring-playbook.md
@@ -1,8 +1,12 @@
 # Configuring the Ansible playbook
 
-Once you have your server and you have [configured your DNS records](configuring-dns.md), you can proceed with configuring this playbook, so that it knows what to install and where.
+To configure the playbook, you need to have done the following things:
 
-You can follow these steps:
+- have a server where Matrix services will run
+- [configured your DNS records](configuring-dns.md)
+- [retrieved the playbook's source code](getting-the-playbook.md) to your computer
+
+You can then follow these steps inside the playbook directory:
 
 - create a directory to hold your configuration (`mkdir inventory/host_vars/matrix.<your-domain>`)
 
diff --git a/docs/getting-the-playbook.md b/docs/getting-the-playbook.md
new file mode 100644
index 000000000..2541da0da
--- /dev/null
+++ b/docs/getting-the-playbook.md
@@ -0,0 +1,41 @@
+# Getting the playbook
+
+This Ansible playbook is meant to be executed on your own computer (not the Matrix server).
+
+In special cases (if your computer cannot run Ansible, etc.) you may put the playbook on the server as well.
+
+You can retrieve the playbook's source code by:
+
+- [Using git to get the playbook](#using-git-to-get-the-playbook) (recommended)
+
+- [Downloading the playbook as a ZIP archive](#downloading-the-playbook-as-a-zip-archive) (not recommended)
+
+
+## Using git to get the playbook
+
+We recommend using the [git](https://git-scm.com/) tool to get the playbook's source code, because it lets you easily keep up to date in the future when [Maintaining services](maintenance-upgrading-services.md).
+
+Once you've installed git on your computer, you can go to any directory of your choosing and run the following command to retrieve the playbook's source code:
+
+```bash
+git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
+```
+
+This will create a new `matrix-docker-ansible-deploy` directory.
+You're supposed to execute all other installation commands inside that directory.
+
+
+## Downloading the playbook as a ZIP archive
+
+Alternatively, you can download the playbook as a ZIP archive.
+This is not recommended, as it's not easy to keep up to date with future updates. We suggest you [use git](#using-git-to-get-the-playbook) instead.
+
+The latest version is always at the following URL: https://github.com/spantaleev/matrix-docker-ansible-deploy/archive/master.zip
+
+You can extract this archive anywhere. You'll get a directory called `matrix-docker-ansible-deploy-master`.
+You're supposed to execute all other installation commands inside that directory.
+
+
+---------------------------------------------
+
+No matter which method you've used to download the playbook, you can proceed by [Configuring the playbook](configuring-playbook.md).
diff --git a/docs/prerequisites.md b/docs/prerequisites.md
index f021a87df..cf270e5d8 100644
--- a/docs/prerequisites.md
+++ b/docs/prerequisites.md
@@ -4,7 +4,7 @@
 
 - [Python](https://www.python.org/) being installed on the server. Most distributions install Python by default, but some don't (e.g. Ubuntu 18.04) and require manual installation (something like `apt-get install python`).
 
-- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for [version requirements](ansible.md#supported-ansible-versions) or alternative ways to run Ansible.
+- the [Ansible](http://ansible.com/) program being installed on your own computer. It's used to run this playbook and configures your server for you. Take a look at [our guide about Ansible](ansible.md) for more information, as well as [version requirements](ansible.md#supported-ansible-versions) and alternative ways to run Ansible.
 
 - either the `dig` tool or `python-dns` installed on your own computer. Used later on, by the playbook's [services check](maintenance-checking-services.md) feature.