# Adding extra development documentation

**URL:** <https://discourse.nodered.org/t/adding-extra-development-documentation/6223>\
**Category:** Developing Nodes\
**Created:** [29 December 2018 21:40 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223 "2018-12-29T21:40:05Z")\
**Posts on this page:** 20\
**Page:** 1

<div class="post-metadata">

**Author:** ![BartButenaers](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bartbutenaers/32/10476_2.png) [@BartButenaers](https://discourse.nodered.org/u/BartButenaers)\
**Post date:** [29 December 2018 21:40 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/1 "2018-12-29T21:40:05Z")

</div>

Hey folks,

When you want to start developing your custom Node-RED nodes, there is currently already a **LOT** of useful information available in the official [documentation](https://nodered.org/docs/creating-nodes/first-node):

![image](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/2X/a/a9c2710c4d79d0005e19a261025e64c21a4a5be2.png)

But I would like to add some extra stuff to it:

- When I started Node-RED two years ago, this information was just not enough for me because:

- The documentation contains nice code examples how to program something, but I would like to have some extra design guidelines on how to use it. E.g. not only explain [how](https://nodered.org/docs/creating-nodes/status) to update a node status, but also explain which kind of information is expected in the status (like Dave has nicely explained [here](https://discourse.nodered.org/t/node-red-dashboard-audio-wish/4798/14?u=bartbutenaers)). There are so many good design guidelines spread (and repeated) across the forum, but would be nice if this kind of information was also in the official documentation.

- When developing nodes, it is very handy to have an idea of how Node-RED technically works. For example which communication goes via webservices, and so on ...

And secondly there is the new [https://github.com/node-red/node-red-ui-nodes](https://github.com/node-red/node-red-ui-nodes), which is specific for UI development. But most of the information for ui-nodes is identical to the information of non-ui nodes ...

**Question** : Not sure at the moment which kind of information needs to be in this repository, instead of in the above developer documentation? Or do we need to repeat _some_ of the information on both places.

Thanks !!  
Bart

---

<div class="post-metadata">

**Author:** ![knolleary](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/knolleary/32/3_2.png) [@knolleary](https://discourse.nodered.org/u/knolleary)\
**Post date:** [29 December 2018 22:14 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/2 "2018-12-29T22:14:51Z")

</div>

Hi Bart. We certainly do want to improve the docs.

There is already activity underway from our friends at Hitachi to put together some better guidelines. This is being doing on the website wiki initially prior to a wider review of the content. This is a new effort in the last month; so much so I've not looked at it yet. You can see what content exists here: [Node Dev Guideline · node-red/node-red.github.io Wiki · GitHub](https://github.com/node-red/node-red.github.io/wiki/Node-Dev-Guideline)

(I'm not sure if the people working on this are active in the forum - they are in the #docs channel on slack. I can't find them here from my mobile, maybe @nisiyama can help join them to this thread)

> [@BartButenaers](#):
>
> **Question** : is it ok if I create a pull request to add this kind of information to the developer [Github page](https://github.com/node-red/node-red.github.io/tree/0695c5f599af4b60ac9edbec4e4863755efe46ce/docs/creating-nodes)? I don't think users are going to find it, if I document it somewhere else on the dark net ...

We made a conscious choice not to document a lot of that material as it isn't for us to document how to use GitHub, git etc and we had more than enough of our own material to write. That isn't to say we shouldnt have an overview, a high level description that then links out to appropriate external docs. But I do not want us to host a git 101 tutorial.

> [@BartButenaers](#):
>
> **Question** : is it ok if I create a pull request to add some of these design guidelines to the developer Github page?

This needs to be coordinated with the effort I mentioned above. It's all good content, and needs to be included.

> [@BartButenaers](#):
>
> **Question** : is it ok if I create a pull request to add some kind of technical diagram to the developer Github page? E.g. a diagram to show that both the flow editor and dashboard communicate via websocket to the flow.

I'm not clear which page you describe as the developer GitHub page? Given there is no content about how the runtime and editor communicate, a diagram would be premature in my opinion.

> [@BartButenaers](#):
>
> **Question** : Not sure at the moment which kind of information needs to be in this repository, instead of in the above developer documentation? Or do we need to repeat _some_ of the information on both places.

We barely have the resources to maintain one set of documentation. So duplicating it is just inviting them to get out of sync. The readme files should given a enough info to explain what the repo is and, if it makes sense, a quick start guide. But should then link to the significant content on [nodered.org](http://nodered.org)

So, in summary, your offers are welcome, but we need to coordinate with other work going on.

And, as I've mentioned before, I'm on vacation right now so whilst I'm keen to nurture this sort of effort, there's only so much I'm in a position to facilitate for the next few days.

---

<div class="post-metadata">

**Author:** ![BartButenaers](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bartbutenaers/32/10476_2.png) [@BartButenaers](https://discourse.nodered.org/u/BartButenaers)\
**Post date:** [29 December 2018 22:59 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/3 "2018-12-29T22:59:07Z")

</div>

> [@knolleary](#):
>
> There is already activity underway from our friends at Hitachi

Thanks for sharing the link. Nice to hear that they are involved...

> [@knolleary](#):
>
> I'm not clear which page you describe as the developer GitHub page?

Ok, I was indeed not clear. I refer _everywhere_ above to the [Creating Nodes](https://nodered.org/docs/creating-nodes/) documentation.

> [@knolleary](#):
>
> But I do not want us to host a git 101 tutorial.

Hmm I forgot to mention that I **don't** have the intention to convert your documentation into an NPM and Github manual. Just would be nice if a novice user could create and publish a custom node, by only reading the '_Creating Nodes_' documentation:

- **NPM** : with only 3 à 4 commands, a novice user can already publish his node on NPM. So I want to keep it **very** short, only the **absolute minimum** required (e.g. mention that you can request a refresh at [flows.nodered.org](http://flows.nodered.org)...).
- **Github** : creating a repository is only a single button click. But it is already important from here on that the data entered is correct (e.g. name should start with 'node-red-contrib-...' or 'node-red-contrib-ui-...'), which not all of the developers follow. Again the absolute minimum!

> [@knolleary](#):
>
> Given there is no content about how the runtime and editor communicate, a diagram would be premature in my opinion.

Indeed this isn't really about developing nodes... Will create my own Github repository to share this kind of information.

> [@knolleary](#):
>
> I'm on vacation right now

Our planet isn't going to implode if you don't have time for this kind of stuff now 😉  
**ENJOY YOUR HOLIDAYS AND SEE YOU NEXT YEAR !!!**

---

<div class="post-metadata">

**Author:** ![knolleary](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/knolleary/32/3_2.png) [@knolleary](https://discourse.nodered.org/u/knolleary)\
**Post date:** [29 December 2018 23:23 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/4 "2018-12-29T23:23:52Z")

</div>

> [@BartButenaers](#):
>
> Indeed this isn't really about developing nodes... Will create my own Github repository to share this kind of information.

Why create your own? It sounds like it belongs in our docs, just a case of figuring out where - my point was there isnt a natural home for that today. So what's the missing section of docs that would just such an image? I know there's the whole topic of adding custom admin endpoints for the editor dialog to call - so I can stop refering people to my stack overflow answer on the subject.

Custom nodes are not really meant to use the websocket Comms link, which is why it isn't mentioned in the docs.

> [@BartButenaers](#):
>
> Our planet isn't going to implode if you don't have time for this kind of stuff now 😉

If I can nudge the oil tanker a little today, in a week's time when I'm back online properly, it'll hopefully be closer to the preferred destination. Which ultimately makes my life easier.

We have so little interest shown by the community to help with things like this, I'm keen to nurture any spark.

---

<div class="post-metadata">

**Author:** ![seth350](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/seth350/32/4617_2.png) [@seth350](https://discourse.nodered.org/u/seth350)\
**Post date:** [30 December 2018 03:20 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/5 "2018-12-30T03:20:57Z")

</div>

Bart and I are working on coming up with some instructional help files for creating a node.  
From what I am reading here, it seems as though there are plenty of irons in the fire already. Even so, it looks like work is in progress writing some of the things I was going to write.  
Given the scope of it all, it’s probably best that I leave it to the architects/owners to come up with their own documentation. You guys know what you need, and trying conveying that need to someone like me is not going to help you guys any. We won’t speak the same language (dev talk).

If I may give my opinion, most of the documentation is probably wrote by developers and ultimately becomes only being understood by developers.

But, perhaps that is a good thing?

---

<div class="post-metadata">

**Author:** ![BartButenaers](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bartbutenaers/32/10476_2.png) [@BartButenaers](https://discourse.nodered.org/u/BartButenaers)\
**Post date:** [30 December 2018 08:31 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/6 "2018-12-30T08:31:06Z")

</div>

Hey @seth350,

From Nick's explanation above, we should only wrie a **quickstart** guide. That is exactly what you were doing this weekend. On the other hand, the documentation that I was writing yesterday, needs to be merged into the Hitachi docs. So you were right on track. And don't forget that also guys like you have to be able to develop their own nodes. You have done a done good job with your lineargauge node.

So I suggest we continue together with the quickstart guide, so more people understand it 😉

Deal?  
Bart

---

<div class="post-metadata">

**Author:** ![dceejay](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/dceejay/32/38_2.png) [@dceejay](https://discourse.nodered.org/u/dceejay)\
**Post date:** [30 December 2018 08:35 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/7 "2018-12-30T08:35:35Z")

</div>

And AFAIK the existing efforts are about generic nodes. The new repository is for ui nodes and has no content (yet) so while some of the basics (like how to publish) will be the same (ie should be linked across) all the scope / ui / template specific bits you have found are all new ground we need to cover.

So yes please carry on !

---

<div class="post-metadata">

**Author:** ![seth350](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/seth350/32/4617_2.png) [@seth350](https://discourse.nodered.org/u/seth350)\
**Post date:** [30 December 2018 08:51 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/8 "2018-12-30T08:51:31Z")

</div>

Deal. 👍

---

<div class="post-metadata">

**Author:** ![BartButenaers](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bartbutenaers/32/10476_2.png) [@BartButenaers](https://discourse.nodered.org/u/BartButenaers)\
**Post date:** [30 December 2018 09:10 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/9 "2018-12-30T09:10:31Z")

</div>

> [@seth350](#):
>
> Deal

Glad I could convince you, because my boss always says that I don't have soft skills. But I just asked my new Google Home Mini device "_give me a compliment_", and she responded "_Bart you are a leader and a real motivator_". So I don't think my boss knows what he is talking about 😂

---

<div class="post-metadata">

**Author:** ![BartButenaers](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bartbutenaers/32/10476_2.png) [@BartButenaers](https://discourse.nodered.org/u/BartButenaers)\
**Post date:** [30 December 2018 10:03 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/10 "2018-12-30T10:03:08Z")

</div>

Hey Dave (@dceejay) ,

I think much of the UI **basics** are covered when we:

- Would explain how to setup **two-way communication** between their custom UI node and a Node-RED flow. For example:

- Would explain how to customize their UI node via the config screen:

Is that a good start? I assume @seth350 might agree, because this covers most of his questions during development of his first node.

---

<div class="post-metadata">

**Author:** ![dceejay](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/dceejay/32/38_2.png) [@dceejay](https://discourse.nodered.org/u/dceejay)\
**Post date:** [30 December 2018 10:35 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/11 "2018-12-30T10:35:28Z")

</div>

Yes sounds good to me.

---

<div class="post-metadata">

**Author:** ![nisiyama](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/nisiyama/32/85_2.png) [@nisiyama](https://discourse.nodered.org/u/nisiyama)\
**Post date:** [30 December 2018 12:27 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/12 "2018-12-30T12:27:40Z")

</div>

Hi, @knolleary @BartButenaers  
Lee-san and Nakata-san are working on _Flow Development Guideline_ and _Node Development Guideline_ that are currently used internaly in our company. We want to integrate these documents into official documents after gradually translating them from Japanese to English.  
I'll inform them abount discussion here. But, unfortunately our company is on vacation until next weekend.  
So, please wait for a while.

---

<div class="post-metadata">

**Author:** ![dceejay](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/dceejay/32/38_2.png) [@dceejay](https://discourse.nodered.org/u/dceejay)\
**Post date:** [30 December 2018 14:45 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/13 "2018-12-30T14:45:00Z")

</div>

I have added a few more words to the node-red-ui-nodes to start off with.  
@nisiyama -san - I have moved the api words from the dashboard wiki over as this is where they should live I think. When/if you are happy to migrate your ui\_list project over (?) into this that would be great. then we can fix up the links to be just local.

Likewise @seth350, @BartButenaers - feel free to start adding widget creation related content. Once we have 2 or 3 we can start to organise it all more logically, then link it into the main docs appropriately.

Thanks

---

<div class="post-metadata">

**Author:** ![seth350](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/seth350/32/4617_2.png) [@seth350](https://discourse.nodered.org/u/seth350)\
**Post date:** [30 December 2018 15:06 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/14 "2018-12-30T15:06:56Z")

</div>

@BartButenaers,  
That was exactly my thinking.

@dceejay,  
I was going to build a template/boiler plate with `myLittleUiNode` showcasing the ability to send configuration from the server side to the client side, and setting up the node editor.

Precisely, making a text node that would allow the user to customize text color and text.  
Including walk-through for the code to make changes to it to make it do something else.  
Also, major code comments that will explain the required sections and where to place the user code.

That alone would have helped me a great deal with my linear-gauge node.

---

<div class="post-metadata">

**Author:** ![dceejay](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/dceejay/32/38_2.png) [@dceejay](https://discourse.nodered.org/u/dceejay)\
**Post date:** [30 December 2018 15:19 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/15 "2018-12-30T15:19:47Z")

</div>

great - very much inline with my thinking also. Would really like 2-3-4 "simple" extra widgets that either show different aspects of how to do things - or grow on top of each other... eg - text, (we have list), table, graphics (eg like you gauge), etc.

Each as a separate directory within this project - but each with its own package.json etc so can be installed directly.

(Hey - maybe even an RTSP one 😉

---

<div class="post-metadata">

**Author:** ![seth350](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/seth350/32/4617_2.png) [@seth350](https://discourse.nodered.org/u/seth350)\
**Post date:** [30 December 2018 20:53 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/16 "2018-12-30T20:53:32Z")

</div>

@dceejay,  
Sounds good. If that is the avenue you guys would like to take, I can do a pull request to add my gauge.  
I am creating another repository for just a simple how-to node `myLittleUiNode`.

I will do a seperate pull request for it when I am ready for you guys to review.

---

<div class="post-metadata">

**Author:** ![dceejay](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/dceejay/32/38_2.png) [@dceejay](https://discourse.nodered.org/u/dceejay)\
**Post date:** [30 December 2018 21:56 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/17 "2018-12-30T21:56:33Z")

</div>

I'm happy for your gauge to be in - and the myLittleUiNode when it's ready.

---

<div class="post-metadata">

**Author:** ![BartButenaers](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bartbutenaers/32/10476_2.png) [@BartButenaers](https://discourse.nodered.org/u/BartButenaers)\
**Post date:** [31 December 2018 14:56 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/18 "2018-12-31T14:56:40Z")

</div>

> [@dceejay](#):
>
> I'm happy for your gauge to be in

Hi @dceejay, just saw that there is again a new UI node ([node-red-contrib-ui-led](https://github.com/Adorkable/node-red-contrib-ui-led)) published. I'm pretty convinced that 2019 will become a year with lots of fancy UI widgets. Looking forward to it...

See you guys next year 🎉 🎆 🎉

---

<div class="post-metadata">

**Author:** ![nisiyama](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/nisiyama/32/85_2.png) [@nisiyama](https://discourse.nodered.org/u/nisiyama)\
**Post date:** [1 January 2019 13:57 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/19 "2019-01-01T13:57:22Z")

</div>

@dceejay Thank you for preparing new repository.  
I have opened a PR that migrates updated **ui\_list** widget example to new repository.

---

<div class="post-metadata">

**Author:** ![seth350](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/seth350/32/4617_2.png) [@seth350](https://discourse.nodered.org/u/seth350)\
**Post date:** [1 January 2019 14:59 UTC](https://discourse.nodered.org/t/adding-extra-development-documentation/6223/20 "2019-01-01T14:59:46Z")

</div>

@dceejay,  
I wanted to ask of the team their preference to how comments should be added to the `.html & .js` file of a node?

Please find `my-little-ui-node` [here](https://github.com/seth350/node-red-ui-nodes/tree/master/node-red-contrib-ui-mylittleuinode)  
and let me know if what I did is acceptable.

Instead of making a long README, I did all of the comments in the node files. My intent was to create blocked sections of the code so a user would know exactly where their code should be placed. It also will show the user what code should be left alone.

There are a few more TODOs in the files to take care of, and I was hoping for advice from the team. Primarily, explaining what some of the functions are for.

Happy New Year!

[Next page](https://discourse.nodered.org/t/adding-extra-development-documentation/6223.md?page=2)