Misc doc updates

Co-Authored-By: Roberto Abdelkader Martínez Pérez <robertomartinezp@gmail.com>

docs/source/theory/philosophy.rst

@@ -2,28 +2,30 @@ Philosophy
 ==========
 
 
-We Provide a Single Static Binary
----------------------------------
+Single Static Binary
+--------------------
 
-- Because it makes deployments easier.
+- Deployment is then as simple as it gets.
+
+- Docker-friendly.
 
 
 Shell Agnostic
 --------------
 
-- Kapow! knows nothing about the shell you are using.
-- It only spawns executables.
-- You can use anything you want that ends interacting with the `data
-  api`.
-- This helps with multiplatform and with future higher level tools.
+- Kapow! knows nothing, and makes no assumptions, about the shell you are using.
+  It only spawns executables.
+
+- You are free to implement a client to the Data API directly if you are so
+  inclined. The spec provides all the necessary details.
 
 
 Not a Silver Bullet
 -------------------
 
-You should not use Kapow! for projects with complex business logic.
+You should not use Kapow! if your project requires complex business logic.
 
 If you try to encode business logic in a shell script, you will **deeply**
 regret it.
 
-Kapow! is for automating simple stuff.
+Kapow! is designed for automating simple stuff.

docs/source/theory/request_life_cycle.rst

@@ -8,26 +8,31 @@ answered by the User HTTP Interface.
 
 #. The request is matched against the route table
 
-#. Kapow! provides a `HANDLER_ID` to identify this request
+#. ``kapow`` provides a `HANDLER_ID` to identify this request and don't mix it
+   with other requests that could be running concurrently.
 
-#. Kapow! spawns the binary specified as entrypoint in the matching route
+#. ``kapow`` spawns the binary specified as entrypoint in the matching route
 
    The default entrypoint is /bin/sh; we'll explain this workflow for now.
 
-   The spawned entrypoint is run with the following variables added to its environment:
+   The spawned entrypoint is run with the following variables added to its
+   environment:
 
    - ``KAPOW_HANDLER_ID``: Containing the `HANDLER_ID`
    - ``KAPOW_DATAAPI_URL``: With the URL of the `data interface`
    - ``KAPOW_CONTROLAPI_URL``: With the URL of the `control interface`
 
-#.  During the lifetime of the shell, the request and response resources are available via these commands:
+#. During the lifetime of the shell, the request and response resources are
+   available via these commands:
 
    - ``kapow get /request/...``
    - ``kapow set /response/...``
 
    These commands use the aforementioned environment variables to read
-   data of the user request and to write the response.
+   data from the user request and to write the response.
 
-TODO: link to resource tree
+   .. todo::
 
-#. When the shell dies, Kapow! finalizes the original request
+      link to resource tree
+
+#. When the shell dies, ``kapow`` finalizes the original request