CLOSES: #77

README.rst

@@ -3,7 +3,7 @@
 
 .. image:: https://circleci.com/gh/BBVA/kapow/tree/master.svg?style=svg
     :target: https://circleci.com/gh/BBVA/kapow/tree/master
-    
+
 **Kapow!** If you can script it, you can HTTP it.
 
 
@@ -15,6 +15,63 @@ the provided code is a Proof of Concept and the final version will not even
 share programming language.  Ye be warned.
 
 
+What is?
+==============
+
+Kapow! is an adapter between the world of Pure UNIX® Shell and a HTTP service.
+
+Some tasks are more convenient in the shell, like cloud interactions, or some
+administrative tools.  On the other hand, some tasks are more convenient as a
+service, like DevSecOps tooling.
+
+Kapow! lies between these two worlds, making your life easier.  Maybe you wonder
+about how this kind of magic can happen; if you want to know the nitty-gritty
+details, just read our `specification </spec>`_;.  Or, if you want to know how
+Kapow! can help you first, let's start with a common situation.
+
+Think about that awesome command that you use every day, something very
+familiar, like ``cloudx storage ls /backups``.  Then someone asks you for an
+specific backup, so you ``ssh`` into the host, execute your command, possibly
+``grepping`` through its output, copy the result and send it back to him.
+And that's fine... for the 100 first times.
+
+Then you decide, let's use an API for this and generate an awesome web server
+with it.  So, you create a project, manage its dependencies, code the server,
+parse the request, learn how to use the API, call the API and deploy it
+somewhere.  And that's fine... until you find yourself again in the same
+situation with another awesome command.
+
+The awesomeness of UNIX® commands is infinite, so you'll be in this situation
+an infinite number of times!  Instead, let's put Kapow! into action.
+
+With Kapow! you just need to create a ``.pow`` file named ``backups.pow`` that
+contains:
+
+```Shell
+    kapow route add /backups \
+        -c 'cloudx storage ls /backups | grep $(kapow get /request/params/query) | kapow set /response/body'
+```
+
+and execute it in the remote host with the command:
+
+```Shell
+    kapow server backups.pow
+```
+
+and that's it.  Done.  You have a web server that people can use to request
+their backups every time they need only by invoking the URL
+`http://remotehost/backups?query=project`
+
+Do you like it? yes?  Then let's start learning a little more, you can access
+the `documentation </doc>`_; section to find installation instructions and some
+examples.
+
+
+
+
+
+
+
 How it was born
 ---------------