Changes from Ghyslain feedback

quick_start/module.rst

@@ -5,7 +5,7 @@ Writing your Module
 
 NStack Modules contain the methods that can be used on the NStack platform. They are the building blocks which can be used to build workflows and applications.
 
-After this tutorial, we will have a simple live Python module deployed to our NStack instance, where it can be hooked up to event and data-sources. 
+After this tutorial, we will have a simple Python module deployed to our NStack instance, where it can be hooked up to event and data-sources. This module has a single method in it which simply counts the number of characters in some text. 
 
 .. note:: Before starting, check that NStack is installed by running ``nstack --version`` in your terminal. If you got information about the version of NStack you have, you're good to go. If that didn't work, check out :doc:`Installation </installation>` again.
 
@@ -34,11 +34,11 @@ A successful ``init`` will have created some files in the directory.
  > ls
  nstack.yaml  requirements.txt  service.py  setup.py
 
-This is the skeleton of an NStack module.  Modules comprise of a configuration file -- `nstack.yaml` -- and your business logic, which in this example is some Python code. 
+This is the skeleton of an NStack module. ``nstack.yaml`` is the configuration file for your module, and ``service.py`` is where the code of your module lives (in this case, it's a Python class). ``requirements.txt`` and ``setup.py`` are both standard files for configuring Python. 
 
 We're going to be concerned with ``nstack.yaml`` and ``service.py``. For a more in-depth look at all these files, refer to :doc:`Module Structure </reference/module_structure>`
 
-``service.py`` is where the business logic of your Python module lives. This is just Python as you would normally write it, with a ``Service`` class that contains the methods we want to use on NStack. NStack prefills it with a sample method, ``numChars``, that counts the number of characters in some text.
+In ``service.py``, there is a ``Service`` class. This is where we would write the methods we want to use on NStack. It is prefilled it with a sample method, ``numChars``, that counts the number of characters in some text.
 
 .. code:: python
 
@@ -93,7 +93,7 @@ To build and publish our module on NStack, we use the ``build`` command.
 
 When we run this, the code in the directory is packaged up and sent to the server, where NStack transforms it into a module.
 
-.. note:: Learn more about how NStack packages and runs your module using containers in the :ref:`Architecture<_architecture>` section.
+.. note:: Learn more about how NStack packages and runs your module using containers in the :ref:`Architecture <architecture>` section.
 
 We can check that our ``numChars`` method is live by running the suggested ``nstack list methods`` command:
 

quick_start/workflow.rst

@@ -4,10 +4,10 @@ Building your Workflow
 =========================
 
 In the previous tutorial, we built and published a Python module using NStack.
-This module had a single method on it, ``numChars``, which counted the number of characters in some text.
-In this tutorial, we're going to turn our method into a HTTP endpoint by building a workflow and connecting it to a `source` and a `sink`.
+This module had a single method on it, ``numChars``, which counted the number of characters in some text. Although it has been published, we cannot talk to it until we connect it to a `source` and a `sink`.
+In this tutorial, we're going to do this, and we'll be using an HTTP endpoint as a `source`, and NStack's built-in log as a `sink`. When we're finished, we will be able to send some text to an HTTP endpoint, and see the length of the text in our log. 
 
-.. note:: Sources generate data which gets sent to your method, and sinks receive the data which your method outputs. Learn more in :ref:`Concepts <_concepts>`
+.. note:: Sources generate data which gets sent to your method, and sinks receive the data which your method outputs. Learn more in :ref:`Concepts <concepts>.`
 
 Let's first refresh ourselves on what the input and output types of our method were by asking NStack:
 
@@ -23,36 +23,37 @@ if you use this source, NStack sets up an HTTP endpoint which you can send JSON-
 As a sink, we are going to use the NStack ``log``,
 which is a simple sink for seeing the output from your method.
 
-.. note:: See a list of available sources and sinks in :ref:`Supported Integrations <_supported_integrations>`
+.. note:: See a list of available sources and sinks in :ref:`Supported Integrations <supported_integrations>`
 
 In full, our workflow is going to look like this:
 
 .. code:: bash
 
   source(http:///demo : Text) | demo.numChars | sink(log:// : Integer)
 
-Let's break it down into parts to see what we're doing:
+
+NStack uses the ``|`` operator to connect statements together, just like in a shell such as ``bash``. We use it to connect together the parts to form our workflow.
+
+Let's break these parts to see what we're doing:
 
 =======================================  ===========
 Part                                     Description
 =======================================  ===========
-``source(http:///demo : Text)``          Use ``http`` as a source, which creates an endpoint on ``/demo``. The ``Text`` statement means it can only create accept and pass on Text.
+``source(http:///demo : Text)``          Use ``http`` as a source, which creates an endpoint on ``/demo``. The ``Text`` statement means it can only accept and pass on Text.
 
 ``demo.numChars``                        The name of the method which we built.
 
 ``sink(log:// : Integer)``               Use NStack's log as a sink. The ``Integer`` statement means it can only accept Integers.
 =======================================  ===========
 
-NStack uses the ``|`` operator to connect statements together, just like in a shell such as ``bash``. We use it to connect together the parts to form our workflow.
-
 To start this workflow with NStack, we use NStack's ``start`` command:
 
 .. code:: bash
 
  > nstack start "source(http:///demo : Text) | demo.numChars | sink(log:// : Integer)"
  Started source(http:///demo : Text) | demo.numChars | sink(log:// : Integer) as process 1
 
-We now have a live HTTP endpoint on ``localhost:8080/demo``, running as process ``1`` on NStack. The HTTP endpoint is configured to accept JSON-encoded values. We defined it to use an input schema of ``Text``, so we will be able to send it any JSON ``string``.
+We now have a live HTTP endpoint on ``localhost:8080/demo``, running as process ``1`` on NStack. The HTTP endpoint is configured to accept JSON-encoded values. We defined it to use an input schema of ``Text``, so we will be able to send it any JSON ``string``. In our JSON, we put ``params`` as the key, and our input as the value:
 
 We can call it using ``curl``:
 
@@ -61,11 +62,11 @@ We can call it using ``curl``:
  > curl -X PUT -d '{ "params" : "Foo" }' localhost:8080/demo 
  Success
 
-And if we look at the log of our process, which we configured as the sink, we will be able to see the result.
+And if we look at the log of our process, which we configured as the sink, we will be able to see the result. Because our process was started with an id of ``1``, we run the following:
 
 .. code:: bash
 
  > nstack log 1
  Feb 17 09:59:26 nostromo nstack-server[8925]: OUTPUT: 3
 
-
+Great!