From 5353d4b00648136dcd3b29391e98a2578c5b6fdd Mon Sep 17 00:00:00 2001
From: Matthias Kretschmann <m@kretschmann.io>
Date: Wed, 18 Apr 2018 18:13:57 +0200
Subject: [PATCH] document forms

---
 README.md      |  5 +++++
 docs/README.md |  1 +
 docs/forms.md  | 19 +++++++++++++++++++
 3 files changed, 25 insertions(+)
 create mode 100644 docs/forms.md

diff --git a/README.md b/README.md
index afe80a0..5d9c99b 100644
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@
 
 ---
 
+* [Documentation](#documentation)
 * [Development](#development)
     * [Prerequisites](#prerequisites)
     * [Get up and running](#get-up-and-running)
@@ -30,6 +31,10 @@
 * [Authors](#authors)
 * [License](#license)
 
+## Documentation
+
+Have a look at the [`docs/`](docs/) folder.
+
 ## Development
 
 The whole website is a Jekyll based site with a Gulp-based build pipeline in front of it.
diff --git a/docs/README.md b/docs/README.md
index e2cc48c..45a37a8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,5 @@
 
+- [Forms](forms.md)
 - [Media kit](mediakit.md)
 - [CSS](css.md)
 - [Testimonials](testimonials.md)
diff --git a/docs/forms.md b/docs/forms.md
new file mode 100644
index 0000000..f2069c3
--- /dev/null
+++ b/docs/forms.md
@@ -0,0 +1,19 @@
+# Forms
+
+We have multiple forms in use throughout the whole site doing the following:
+
+| Form        | Actions        |
+| ------------|-------------|
+| `/contact`  | send to CC emails, Slack message |
+| `/services` | send to CC emails, Slack message, add new row to Google Sheets |
+| `/cla`      | 2 different forms, send to CC emails |
+
+Initial form sending is handled via formspree.io with a Gold account. As form submissions arrive there, Formspree sends out the received submissions to the email addresses setup as CC in [our site config](../_config.yml).
+
+Submissions are processed further like so:
+
+_Formspree -> Zapier Email Parser -> Zapier -> Slack & Google Sheets_
+
+The Zapier email parser is a special mailbox provided by Zapier which receives form submissions from Formspree, parses the content of those emails and extracts data fields out of it.
+
+The parser as a source then provides the structured data to our Zapier tasks.