Add first parts of reworked flow-dev guide

Author: knolleary

_includes/developing-flows-toc.html

@@ -0,0 +1,30 @@
+<ul class="toc">
+    <li class="toc-expander"><div>V</div></li>
+    <li class="tocheader">
+        <ul>
+            <li class="toctitle active"><a href="/docs/developing-flows/">Developing Flows</a></li>
+            <li {% if page.url == "/docs/developing-flows/flow-structure" %}class="active"{% endif %}><a href="/docs/developing-flows/flow-structure">Flow structure</a></li>
+            <li {% if page.url == "/docs/developing-flows/message-design" %}class="active"{% endif %}><a href="/docs/developing-flows/message-design">Message design</a></li>
+            <li {% if page.url == "/docs/developing-flows/error-handling" %}class="active"{% endif %}><a href="/docs/developing-flows/error-handling">Error handling</a></li>
+            <li {% if page.url == "/docs/developing-flows/documenting-flows" %}class="active"{% endif %}><a href="/docs/developing-flows/documenting-flows">Documenting Flows</a></li>
+        </ul>
+        <hr>
+        <i>
+        <ul>
+            <li {% if page.url == "/docs/developing-flows/designing" %}class="active"{% endif %}><a href="/docs/developing-flows/designing">Designing</a></li>
+            <li {% if page.url == "/docs/developing-flows/implementation" %}class="active"{% endif %}><a href="/docs/developing-flows/implementation">Implementation</a></li>
+            <li {% if page.url == "/docs/developing-flows/readability" %}class="active"{% endif %}><a href="/docs/developing-flows/readability">Readability</a></li>
+            <li {% if page.url == "/docs/developing-flows/multiple-developers" %}class="active"{% endif %}><a href="/docs/developing-flows/multiple-developers">Project</a></li>
+            <li {% if page.url == "/docs/developing-flows/non-functional" %}class="active"{% endif %}><a href="/docs/developing-flows/non-functional">Non-functional requirements</a></li>
+        </ul>
+        </i>
+    </li>
+</ul>
+<script>
+    $(function() {
+        var pageToc = $("<ul></ul>").appendTo(".toc li.active:not(.toctitle)");
+        $(".docs-content h3,.docs-content h4").each(function() {
+            $('<li id="toc-item-'+$(this).attr('id')+'"><a style="font-size: 0.9em; padding-left: 50px;" href="#'+$(this).attr('id')+'">'+$(this).text()+'</a></li>').appendTo(pageToc)
+        })
+    })
+</script>

_includes/toc-developing-flows.html

@@ -0,0 +1,3 @@
+{% assign parent_url = '/docs/developing-flows/' %}
+{% assign parent_slug = 'developing flows' %}
+{% include docs-content.html %}

_layouts/docs-developing-flows.html

@@ -1,18 +1,20 @@
 ---
-layout: docs
-toc: developing-flows-toc.html
-title: Designing flow
+layout: docs-developing-flows
+toc: toc-developing-flows.html
+title: Designing flows
 ---
 
+***This content is under review and may not form part of the final flow developer guide***
+
 ### Development steps  
- 
+
 If a project needs complicated logic, it is better to design flow before starting development. After that, you create flows based on the flow design. In this subsection, we show an overview of whole recommended steps of design and development.  
- 
+
 * Design  
    - Flow structure  
    - Message  
 * Implementation  
- 
+
 ### Designing flow structure  
 
 {% comment %}
@@ -39,7 +41,7 @@ If you are developing with multiple developers, it is better to design flows for
 
 #### Subflow
 
-If the same processing needs to be repeated, creating the same nodes sequence several times will not only reduce readability, but will also require changing all applicable nodes, even when they need to be modified. 
+If the same processing needs to be repeated, creating the same nodes sequence several times will not only reduce readability, but will also require changing all applicable nodes, even when they need to be modified.
 You can solve these problems by turning nodes into subflow, and changing icons.
 
 <div style="text-align: center">
@@ -49,8 +51,8 @@ You can solve these problems by turning nodes into subflow, and changing icons.
 For example, if the process of sending e-mail is written as a sub-flow, it can be reused to create a flow in which other processes send e-mail.
 
 ### Designing messages  
- 
-There are risks that multiple nodes have dependencies by messages passing through nodes. For other developers to reuse flows, it is important to design messages so that dependencies get to be relaxed. 
+
+There are risks that multiple nodes have dependencies by messages passing through nodes. For other developers to reuse flows, it is important to design messages so that dependencies get to be relaxed.
 
 {% comment %}
 This chapter proposes a guide about designing message.  
@@ -84,7 +86,7 @@ You better to design the messages before implementing a flow.
 
 {% comment %}
 *`msg` is a JavaScript object that contains a key-value structure like JSON. While a `msg` transits across multiple nodes, the nodes use some keys and values of the `msg`. If two or more nodes of them use the same key for different their own purposes, preparing `msg` for input of the nodes is so difficult.*  
- 
+
 *Therefore, strategy of key-value structure are needed and this subsection describes it as followings,*   
 {% endcomment %}
 
@@ -128,9 +130,9 @@ This verification process also expresses the boundaries of dependencies between
 {% endcomment %}
 
 #### Keeping properties  
- 
+
 In the case of using `Function` node, you can prepare output messages by creating new `msg` objects. However, the output messages may not have some properties that the input message has. This means that properties that should be kept in your flow has lost. Since this can be a cause of serious bugs, preparing output messages based on an input message is better, instead of creating new `msg`.  
- 
+
 #### Add tag into `msg` to distinguish a node that sent the `msg`  
 
 {% comment %}
@@ -146,7 +148,7 @@ Specifically, you assign a tag that identifies the execution path as a message p
 </div>
 
 #### Using persistent storage outside of Node-RED  
- 
+
 If you handle the large amount of data, it is **not** recommended to set the data into `msg` since `msg` can exhaust available memory.
 
 {% comment %}
@@ -173,7 +175,7 @@ You can also make the debugging process easier by adding error handling processi
 
 
 #### Processing messages in order of their arrival  
- 
+
 Since Node-RED (JavaScript) processes asynchronously, a node cannot assume that it executes process for arrival `msgs` by the order of arrival.    
 
 You should design the flow so that processing does not depend on the order in which messages arrive.
@@ -182,8 +184,8 @@ That is, your flow should produce the correct result even if messages arrive in
 If you want to design the flow depending on messages in order, you should use `Sort` node. You can check how to use `Sort` node at **Sequential guarantee** of [Non-functional requirements](non-functional).
 
 {% comment %}
-If you want to assume processes by the order of arrival, try this code. 
- 
+If you want to assume processes by the order of arrival, try this code.
+
 ```javascript  
 // Accumulation of messages  
 var msgs = context.get('messages') || [];  
@@ -192,6 +194,6 @@ if(msgs.length === ...) {
   ... // Process messages  
 }  
 context.set('messages', msgs);  
- 
+
 ```  
 {% endcomment %}

docs/developing-flows/designing.md

@@ -0,0 +1,115 @@
+---
+layout: docs-developing-flows
+toc: toc-developing-flows.html
+title: Documenting flows
+slug: documenting flows
+---
+
+In any programming language, a vital part of creating easy-to-maintain code is to ensure it is also well documented.
+
+Good documentation serves a number of purposes:
+
+1. Whilst everything may seem obvious as you are building a flow, your future self will thank you for providing some description of the details when you come back to it later.
+2. If you are sharing a flow with others, it will help them understand what it is doing and how it works.
+3. If a flow provides an external API you will want to document how that API should be used - what properties or parameters are expected.
+4. When you write documentation, the act of writing out the behaviour could well help you identify parts that could be improved.
+
+In a visual programming environment like Node-RED, the documentation can take a number of forms.
+
+- The flows can be read in the workspace to see the logical flow of events. You should make sure the purpose of each node is easily identified and that they are well laid out to minimise how much wires cross each other.
+- Groups can be used to identify discrete sections of the flows.
+- Moving commonly used parts into subflows can help reduce the visual complexity of the flow.
+- More complete documentation can be added at the node, group or tab level
+
+
+### Laying out flows
+
+The [flow structure](flow-structure) section of this guide looked at how to arrange the logical components of your flows. This section considers the visual appearance of the flow layout.
+
+The goal is to make it easy to follow the flow without having to jump around the workspace or have to follow multiple wires that cross each other and appear tangled.
+
+The approach that gives the greatest legibility is to keep each unit of processing on a single horizontal line wherever possible. The editor's default behaviour of snapping nodes to a grid on the tab helps keep them aligned.
+
+<div class="figure">
+    <img src="./images/node-arrangement-sample.png" alt="Placeholder caption"/>
+    <p class="caption">Placeholder caption</p>
+</div>
+
+If there is a node that has more than one output port, aligning the branched flow vertically makes it easy to compare and contrast the flows.
+
+<div style="width: 600px" class="figure">
+  <img src="images/placeholder.png" alt="Link nodes">
+  <p class="caption">Placeholder for image: Cut above image in half - move Power Usage Calculation Service half here</p>
+</div>
+
+When a flow gets too long, arranging some nodes vertically can be used to good effect. In the following figure, some of the nodes are arranged vertically to imply a relationship between them. It is easier to understand the nature of the overall flow if it is visually obvious what smaller sections it is comprised of and how they relate to each other.
+
+<div class="figure">
+    <img src="./images/node-vertical-arrangement.png" alt="Placeholder caption"/>
+    <p class="caption">Placeholder caption</p>
+</div>
+
+In some cases, these smaller sections may be candidates for moving to subflows that will reduce the visual complexity of the flow. That is particular true if that smaller section could be reused elsewhere in the flows.
+
+### Naming nodes
+
+Most nodes have a `name` property that can be used to customise the label they display in the workspace. This should be used to properly label the key points of a flow.
+
+For example, if a Change node has a single rule that sets `msg.payload` to the current time, its default label will be `set msg.payload`. That helps somewhat, but it doesn't reveal the full purpose of the node. A name of `Get current time` would be much clearer.
+
+There is a balance to be considered here. The longer the label, the more space it needs in the flow. The shorter the label, the less information it can share.
+
+For some nodes, it might be appropriate to hide the label altogether to minimise the horizontal space it uses in the flow - giving more room to other nodes.
+
+Along with the label, nodes can also have a custom icon. For example, if you have a number of MQTT In nodes for different types of device, customising the icon to match the type of device could be helpful. This should be used with care as the icon is one of the main ways of identifying the type of a particular node
+
+Choosing good names for things applies just as much to the tabs and subflows used.
+
+It also very important for Link nodes. Without a name set, you have to use the Link node's internal ID when creating links between different tabs. That makes it hard to identify the right target node and mistakes can happen. If you consider the Link nodes as providing APIs between the different tabs, then a good choice of naming scheme will be needed.
+
+### Adding port labels
+
+If a node has multiple outputs it can be hard to follow the logic if it is not clear on what condition a message may be sent from a particular output.
+
+This is where adding port labels can help document the intended logic.
+
+For example, the Switch node provides default labels for its outputs that are shown when the mouse hovers over them. They can help quickly identify the purpose of each branch in the flow.
+
+Whilst the default labels may be sufficient in the context of the flow itself, it is also possible to custom labels to provide more detailed information.
+
+<div style="width: 600px" class="figure">
+  <img src="images/placeholder.png" alt="Link nodes">
+  <p class="caption">Placeholder for image: Port labels</p>
+</div>
+
+### Inline Comments
+
+The Comment node can be used to add inline comments to the flow - both the node's label, but also its description that will show in the Information sidebar when selected.
+
+By indenting the flows on the page, you can indicate an implied grouping of the different components.
+
+<div style="width: 600px" class="figure">
+  <img src="images/placeholder.png" alt="Link nodes">
+  <p class="caption">Placeholder for image: Indenting with Comments</p>
+</div>
+
+### Grouping nodes
+
+A more explicit arrangement of the flows can be achieved by grouping related nodes together.
+
+The background colour of each group can also be used to highlight different types of group.
+
+<div style="width: 600px" class="figure">
+  <img src="images/placeholder.png" alt="Link nodes">
+  <p class="caption">Placeholder for image: Grouping nodes</p>
+</div>
+
+### Adding longer documentation
+
+All of the techniques discussed so far relate to the visual appearance of the flows. In order to add more in depth documentation, something more is needed.
+
+Every node, group and tab can have longer-form documentation added under Description tab in their edit dialog. This help can be formatted using Markdown and including lists, tables and links.
+
+This longer format of documentation is useful where more explanation is needed of a flow's purpose, or some more complex logic needs to be described.
+
+It is also useful where a flow provides an external API of some sort - providing as much detail as it needed for other developers to use the API.

docs/developing-flows/documenting-flows.md

@@ -0,0 +1,13 @@
+---
+layout: docs-developing-flows
+toc: toc-developing-flows.html
+title: Error handling
+slug: error handling
+---
+
+ - How to handle errors in flows
+   - what can or cannot be caught be a Catch node
+ - Where Status node can be used
+
+ - Layout of Catch/Status nodes in relation to what they target
+ - Avoiding loops