Reworked Flow Development Guide by knolleary · Pull Request #163 · node-red/node-red.github.io · GitHub

This PR represents the working copy of the Flow Development Guide. It is still being written - the PR is to share progress and get feedback.

This PR contains the changes from the following PRs:

Add Non-functional requirements chapter of flow-dev-guide #106 Add Non-functional requirements chapter of flow-dev-guide
Add Project chapter of flow-dev-guide #105 Add Project chapter of flow-dev-guide
Add Readability chapter of flow-dev-guide #102 Add Readability chapter of flow-dev-guide
Add Implementation chapter of flow-dev-guide #101 Add Implementation chapter of flow-dev-guide
Add Designing chapter of flow-dev-guide #99 Add Designing chapter of flow-dev-guide
Add introduction of flow-dev-guide #98 Add introduction of flow-dev-guide

The content from those PRs has provided the starting point for the guide. Not all of the content from those PRs will be in the final guide.

The working draft of the guide contains the sections:

Flow Dev guide index page
Flow structure
Message design (not yet written)
Error handling (not yet written) see my comment below
Documenting Flows

The current version of this branch can be viewed here: https://new.nodered.org/docs/developing-flows/

* Pages to discuss chapter composition of flow dev guide * Modified pages to discuss chapter composition

* Pages to discuss chapter composition of flow dev guide * Modified pages to discuss chapter composition * Renamed 'Practiec'->'Developing Flows'

…owguide

I have removed the separate Handling Errors section of the guide as I realised we already have a section on how to do error handling in the main user guide.

Instead, I have added a smaller section to the Flow Structure guide that talks about how to layout the error handling and not about how to do error handling.

First pass.

#107 is part of the node development guideline. Therefore, it can be removed from this flow development guideline.

@kazuhitoyokoi you are right - #107 is not included in this PR. I listed it by mistake.

To make it easier to review this guide, I have set https://new.nodered.org - which is the flowdev branch.

The flow developer guide can be found here: https://new.nodered.org/docs/developing-flows/

Made some minor updates to reflect the comments from @dceejay - have updated https://new.nodered.org/docs/developing-flows/ with the latest

I have now added the Message section to the guide - https://new.nodered.org/docs/developing-flows/

This completes my first full pass through of the guide.

Question: is there any more content from the Hitatchi guide that should be added to the guide?

I would like to remove the extra Hitachi content before opening it for wider review with the community.

Thank you for your confirmation. I checked the website. This pull request contains all of the contents from Hitachi.

@kazuhitoyokoi I need to clarify what I plan to do as I'm not sure from your reply if it is clear.

Yes this PR contains all of the content from Hitachi. But the plan is to delete all of the pages from Hitachi because the information has been rewritten and included in the three sections I have been working on.

I want to make sure you are happy that the three sections I have written cover everything you think it should and that we are okay to delete the hitachi pages.

A few extra bits

do we want to emphasise payload - eg like below - or maybe just bold

should this be msg.payload to link to the msg.topic heading below

just a Function node ? (Ok I get for most users yes... but...)

The Function node is the only node a user can explicitly create a new message object which is why it is singled out here.

supefluous

maybe an image of the "appearance tab" in config to show how to get to shorten the name

... also possible for custom ...

Link to grouping docs ? Or cut/paste blog post info to here ?

In intro para 3 - I think it is also worth adding a link to the YouTube introduction channel - as that is a good resource.
Do we want to add links to other parts of the docs - eg re context ? and or cookbook ?

@knolleary I misunderstood your question. Because today is a holiday in Japan, I will answer it on Monday after checking a little with Hitachi colleagues. Please wait a moment. 🙏

No rush - want to make sure we get this right.

I hope this plan does not come as a surprise - I have been saying since the start of reviewing the flow dev guide that I felt the best approach was to take the information from the Hitachi content and rework it into a slightly different shape.

@knolleary Thank you for waiting. Today, I talked about it with Hitachi colleagues. Because three sections contain key points, we agree with your decision. You can delete the Hitachi pages.

Thanks @kazuhitoyokoi

And please do remember, this is not a 'finished' guide - we can add extra content at any time. So if there are other topics you think it should cover in the future, then open an issue/pr and we can discuss.

@knolleary I appreciate your consideration. Okay, we will suggest a discussion if we have feedback from the Japanese community. 😁

I've updated flow dev guide to remove the extra pages. I'm going to share a link for the wider community to provide some feedback before we publish.

In terms of content, we still need to:

create the images
ensure consistent formatting when referencing nodes or message properties
add links to related parts of the docs and videos

Going to merge this content as it currently stands.

I'm sure there's more to add, particularly around Performance, but I'd rather get this material published and available.

knolleary and others added 27 commits January 31, 2019 10:42

Create Flow Dev Guide placeholder

97354a7

Pages to discuss chapter composition of flow dev guide

6fbc650

Modified pages to discuss chapter composition

37313b4

Add pages to discuss flow dev guide (#92 )

cbaed1c

* Pages to discuss chapter composition of flow dev guide * Modified pages to discuss chapter composition

Renamed 'Practiec'->'Developing Flows'

d0d582a

Renamed 'Practice' -> 'Developing Flows'

35c743a

Modified the title "Practice" to "Developing Flows" (#94 )

429f2f1

* Pages to discuss chapter composition of flow dev guide * Modified pages to discuss chapter composition * Renamed 'Practiec'->'Developing Flows'

Merge remote-tracking branch 'upstream/flow-dev-guide' into master-fl…

8203277

…owguide

Add contents of introduction

32a275b

Add contents of Designing flow

367772d

add images

0fdddfb

add contents of Implementation chapter

16cd819

Add contents of Readability chapter

cecf863

add contents of project chapter

ca7e7d9

add contents of nonfunctional chapter

e7c33e5

modify comment out command

3af2168

modify comment out command

383f944

modify comment out command

af8cc80

modify comment out command

9a9e752

Merge branch 'pr_98' into flowdev

cc87231

Merge branch 'pr_99' into flowdev

9f085b2

Merge branch 'pr_101' into flowdev

c79c148

Merge branch 'pr_102' into flowdev

03628c8

Merge branch 'pr_105' into flowdev

208431b

Merge branch 'pr_106' into flowdev

ff9e595

Add first parts of reworked flow-dev guide

f9d10d5

Remove error handling flow dev section

05dfeec

knolleary requested review from dceejay and kazuhitoyokoi July 16, 2020 14:20

dceejay reviewed Jul 17, 2020

View reviewed changes

knolleary added 2 commits July 21, 2020 15:17

Update with comments

4ecfaad

Clarify where node docs are shown

497ee55

Add message design section

a252880

dceejay reviewed Jul 23, 2020

View reviewed changes

Update flow dev to main content

87252e8

knolleary marked this pull request as ready for review July 27, 2020 22:15

Update from review comments

94410f3

kazuhitoyokoi approved these changes Aug 3, 2020

View reviewed changes

Add images to flow dev guide

1a5ae51

knolleary merged commit d922100 into master Aug 5, 2020

knolleary deleted the flowdev branch August 5, 2020 15:14

+              The messages that pass through a flow are plain JavaScript objects that can have
+              properties set on them.
+              They usually have a payload property - this is the default property that most nodes

+              This section looks at some of the choices you need to make when deciding how to
+              stucture the messages in your flows.
+              ### Working with the payload


		This highlights an important principle: nodes should not modify or remove properties on messages that are not related to their functionality.

		For example, in most cases, a Function node should send on the same message object it received rather than create a new message object.

		As with programming in general, the choice of good property names is also important. They should be self-describing to help with later debugging and understanding of the flow. For example, `msg.temperature` is much more understandable than `msg.t`.


		## No newline at end of file

		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.


		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.


		### Grouping nodes

		A more explicit arrangement of the flows can be achieved by grouping related nodes together.

Reworked Flow Development Guide by knolleary · Pull Request #163 · node-red/node-red.github.io · GitHub

Uh oh!

Reworked Flow Development Guide - #163

Reworked Flow Development Guide#163knolleary merged 33 commits intomasternode-red/node-red.github.io:masterfrom flowdevnode-red/node-red.github.io:flowdevCopy head branch name to clipboard

Conversation

knolleary commented Jul 13, 2020 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

knolleary commented Jul 16, 2020

Uh oh!

dceejay left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kazuhitoyokoi commented Jul 21, 2020

Uh oh!

knolleary commented Jul 21, 2020

Uh oh!

knolleary commented Jul 21, 2020

Uh oh!

knolleary commented Jul 23, 2020

Uh oh!

kazuhitoyokoi commented Jul 23, 2020

Uh oh!

knolleary commented Jul 23, 2020

Uh oh!

dceejay left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dceejay commented Jul 23, 2020

Uh oh!

kazuhitoyokoi commented Jul 24, 2020

Uh oh!

knolleary commented Jul 24, 2020

Uh oh!

kazuhitoyokoi commented Jul 27, 2020

Uh oh!

knolleary commented Jul 27, 2020

Uh oh!

kazuhitoyokoi commented Jul 27, 2020

Uh oh!

knolleary commented Jul 27, 2020

Uh oh!

knolleary commented Aug 5, 2020

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Reworked Flow Development Guide#163
knolleary merged 33 commits into
masterfrom
flowdev

knolleary commented Jul 13, 2020 •
edited
Loading