From d08c6c72e732d38a6a8fa5156da8f6e3488d242f Mon Sep 17 00:00:00 2001
From: pancho horrillo <pedrofelipe.horrillo@bbva.com>
Date: Mon, 25 Nov 2019 18:05:50 +0100
Subject: [PATCH] doc: more work on _brainstorming.rst

Co-authored-by: Hector Hurtado <hector.hurtado@bbva.com>
---
 docs/source/tutorial/_brainstorm.rst | 54 ++++++++++++++++------------
 1 file changed, 31 insertions(+), 23 deletions(-)

diff --git a/docs/source/tutorial/_brainstorm.rst b/docs/source/tutorial/_brainstorm.rst
index ad8d6a4..34c9eb4 100644
--- a/docs/source/tutorial/_brainstorm.rst
+++ b/docs/source/tutorial/_brainstorm.rst
@@ -41,19 +41,19 @@ User Journey
 #. Actions over the server. Launch database backup script with an HTTP call.
 
   - User Learns: Add a route that executes a command locally.
-  - Kapow! Concepts: `kapow route add` 
+  - Kapow! Concepts: `kapow route add`
   - Problem/Motivation: Each time an ACME project is finished it is
-    desirable to make a backup of the entire database. Given that the
+    desirable to make a backup of the entire database.  Given that the
     database server is a critical machine we don't want to grant SSH
-    access to lowly developers. The script is very fast because the
+    access to lowly developers.  The script is very fast because the
     database is small (for now).
-  - Solution: Instead of launching the script via SSH shell we can
-    provide an HTTP endpoint to perform the task.
+  - pre-Kapow! solution: Launching the script via SSH shell.
     ```
     ssh user@server
     $ ./backup_db.sh
     ```
-  - Final Kapow!:
+  - Kapow!-enabled solution: Provide an HTTP endpoint that when accessed
+    triggers the run of the backup script.
     ```
     curl -X PUT http://server:8080/db/backup
     ```
@@ -65,9 +65,12 @@ User Journey
 
   - User Learns: Execute local commands and output it results to the HTTP body.
   - Kapow! Concepts: `kapow set /response/body`
-  - Problem/Motivation: 
-  - Solution:
-  - Final Kapow!:
+  - Problem/Motivation: The backup script produces a log on /tmp/backup_db.log.
+    We want to share this log over HTTP to give users feedback about the backup
+    process result.
+  - pre-Kapow! solution: SSH into the host + cat /tmp/backup_db.log.
+  - Kapow!-enabled solution: Provide an endpoint that returns the contents of
+    /tmp/backup_db.log.
     ```
     cat /var/log/backup_db.log | kapow set /response/body
     ```
@@ -76,10 +79,16 @@ User Journey
 
   - User Learns: Get a parameter from the user and use it to select the
     script.
-  - Kapow! Concepts: `kapow get /request/params` 
-  - Problem/Motivation:
-  - Solution:
-  - Final Kapow!:
+  - Kapow! Concepts: `kapow get /request/params`
+  - Problem/Motivation: /tmp/backup_db.log keeps growing. It's about 100MB now.
+    The users are fed up already.  We need a way to be more selective in the data
+    we dump.
+  - pre-Kapow! solution: SSH into the host, and then find a way to extract the
+    required data from the log file. It would entitle using some combination of
+    grep, tail, etc.  Or we could provide a bespoke shell script to accomplish
+    this task.
+
+  - Kapow!-enabled solution:
     ```
     LINES="$(kapow get /request/params/lines)"
     FILTER="$(kapow get /request/params/filter)"
@@ -93,16 +102,16 @@ User Journey
   - User Learns: Compose complex HTTP responses with more than one local command.
   - Kapow! Concepts: HEREDOC and subshells
   - Problem/Motivation:
-  - Solution:
-  - Final Kapow!:
+  - pre-Kapow! solution:
+  - Kapow!-enabled solution:
     ```
     {
       echo Memory:
-      free -m 
-      echo ================================================================================ 
+      free -m
+      echo ================================================================================
       echo Load:
       uptime
-      echo ================================================================================ 
+      echo ================================================================================
       echo Disk:
       df -h
     } | kapow set /response/body
@@ -113,8 +122,8 @@ User Journey
   - User Learns: Format a complex HTTP response with JSON format to feed the corporate dashboard.
   - Kapow! Concepts: backtick interpolation and `kapow set /response/headers`
   - Problem/Motivation:
-  - Solution:
-  - Final Kapow!:
+  - pre-Kapow! solution:
+  - Kapow!-enabled solution:
     ``` DON'T HANDWRITE JSON
     echo "{memory: `free -m`, ...uups..}'  | kapow set /response/body
     ```
@@ -132,10 +141,9 @@ Ideas
 - /request/params -> Filter the results of a backup query
 - Use redirects to from one Kapow! server to another. I.e: 192.168.1.1/backups/{path:.*} --> 192.168.1.2/<path>
 - /request/files -> Firma el fichero que sube el usuario y te lo devuelve firmado.
-  
-  
+
+
 .. note::
 
    Add this to serve the webpage that uses the implemented HTTP API
    kapow route add / -c 'kapow set /resonse/headers/Content-Type text/html ; curl --output - http:// | kapow set /response/body'
-