doc: Update README and NEXT

NEXT.md

@@ -1,4 +1,34 @@
-Coming next
+Upcoming
 ===
 
-- [ ] Remote training of the interpreter for when you have large training data and you are deploying pytlas on a small device
+In this library
+---
+
+- [ ] Remote training of the interpreter for when you have large training data and you are deploying pytlas on small devices
+
+Big plans
+---
+
+If you wish to contribute, here is what I have in my head for this project :)
+
+**pytlas** is a library and as such does not provide any end user interface (except the REPL). I've done some projects such as the [server](https://github.com/atlassistant/pytlas-server) and [mobile](https://github.com/atlassistant/pytlas-mobile) to expose this library over websockets and connect to it using a mobile client but there's still many stuff to do.
+
+The **big plan** is to provide a `pytlas-broker` which will exposes agents via MQTT to provide a better integration with other IoT systems using simple topics listed below.
+
+This broker project will expose two entry points: `BrokerServer` and `BrokerClient`. Discovery for the MQTT server should be possible using [avahi](https://gist.github.com/marciogranzotto/20e45b83bbcca11e267708b10507c54a).
+
+### Client to Server
+
+- `atlas/<uid>/ping`: Creates an agent if needed
+- `atlas/<uid>/parse`: Ask pytlas to parse a raw message
+
+### Server to Client
+
+- `atlas/<uid>/pong`: Reply to ping requests when the agent is ready
+- `atlas/<uid>/ask`: Ask something to the user
+- `atlas/<uid>/answer`: Answer something to the user
+- `atlas/<uid>/context`: Switched to a particular context
+- `atlas/<uid>/thinking`: Started processing a message
+- `atlas/<uid>/done`: Stopped processing a message
+
+Once that's done, I've got some work in progress for a pod on a RPI which always listen using [snowboy](https://snowboy.kitt.ai/), do some STT using Google Cloud Speech for now (waiting for DeepSpeech...), push the transcript to pytlas and reply back using svox pico. Sources will be available soon, I just need to refactor a little bit.

README.rst

@@ -28,7 +28,7 @@ Want to get your feet wet? Have a look at the `example/skills` folder to see how
 Documentation
 -------------
 
-The documentation is hosted on readthedocs here `https://pytlas.readthedocs.io <https://pytlas.readthedocs.io>`_. It still needs some improvement so don't hesitate to help!
+The documentation is hosted on readthedocs here `https://pytlas.readthedocs.io <https://pytlas.readthedocs.io>`_.
 
 Installation
 ------------
@@ -45,3 +45,26 @@ Testing
 
   $ pip install -e .[snips,test]
   $ python -m nose --with-doctest -v --with-coverage --cover-package=pytlas
+
+Contributing
+------------
+
+Contributions are **welcome**! **pytlas** is being developed on my spare time so every help is greatly appreciated to push this project further.
+
+I have ideas!
+~~~~~~~~~~~~~
+
+Don't hesitate to submit them in the repo and we'll see what can be done.
+
+I have skills & time!
+~~~~~~~~~~~~~~~~~~~~~
+
+Great, have a look at `NEXT.md <NEXT.md>`_ to see the big plans for upcoming releases or fix unresolved issues to start.
+
+I have money!
+~~~~~~~~~~~~~
+
+.. |liberapay| image:: https://liberapay.com/assets/widgets/donate.svg
+    :target: https://liberapay.com/YuukanOO/donate
+
+If you want to donate to help me find more time to work on **pytlas** and similar projects, you can support me on liberapay |liberapay|, thanks ❤️!

docs/index.rst

@@ -30,7 +30,7 @@ Ever wanted to develop your own Alexa, Siri or Google Assistant and host it your
 
 .. warning::
 
-    **pytlas** being a library, it does not handle speech recognition and synthesis. It only handles text inputs. If you want it to be able to interact with the voice, you must write a :ref:`client` (check `pytlas-mobile <https://github.com/atlassistant/pytlas-mobile>`_ to see the official mobile client implementation).
+    **pytlas** being a library, it does not handle speech recognition and synthesis. It only handles text inputs. If you want it to be able to interact with the voice, you must write a :ref:`client` which will call the library internally.
 
 .. toctree::
   :maxdepth: 2

docs/writing_skills/settings.rst

@@ -1,7 +1,7 @@
 Settings
 ========
 
-Settings provides a basic handling of providing configuration variable to the user.
+Settings provides a basic handling to enable the user to configure the system.
 
 When you use the `pytlas repl`, you can provide a config file that will be parsed using `ConfigParser <https://docs.python.org/3/library/configparser.html>`_. If an environment variable matching `SECTION_SETTING` is available, it will override the config file value.
 
@@ -11,6 +11,9 @@ When you use the `pytlas repl`, you can provide a config file that will be parse
 
   from pytlas import settings, intent
 
+  # Load a setting file
+  settings.load('file/path/pytlas.conf')
+
   # Get a string
   settings.get('openweather_key', 'a default value', section='pytlas.weather')
 
@@ -32,4 +35,7 @@ When you use the `pytlas repl`, you can provide a config file that will be parse
     # Inside an handler, you can pass agent metadata to `additional_lookup`
     # With this call, agent meta will take precedence over env and file settings, this
     # is useful to allow agent to override some settings such as api keys.
+    #
+    # If you do so, the `additional_lookup` will be check as if it was the env by using
+    # the key PYTLAS_WEATHER_OPENWEATHER_KEY.
     settings.get('openweather_key', 'a default value', section='pytlas.weather', additional_lookup=r.agent.meta)