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:
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:
I needed to know the basics of NPM
I needed to create my first Github repository
I needed to publish my node on NPM
...
Just didn't knew where to get started, with all those technologies that were completely new for me. And I don't think I'm the only Node-RED user that has those kind of questions.
Question: is it ok if I create a pull request to add this kind of information to the developer Github page? I don't think users are going to find it, if I document it somewhere else on the dark net ...
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 to update a node status, but also explain which kind of information is expected in the status (like Dave has nicely explained here). 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.
Question: is it ok if I create a pull request to add some of these design guidelines to the developer Github page?
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 ...
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.
And secondly there is the new 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.
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
(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)
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.
This needs to be coordinated with the effort I mentioned above. It's all good content, and needs to be included.
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.
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
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.
Thanks for sharing the link. Nice to hear that they are involved...
Ok, I was indeed not clear. I refer everywhere above to the Creating Nodes documentation.
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...).
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!
Indeed this isn't really about developing nodes... Will create my own Github repository to share this kind of information.
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 !!!
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.
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.
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.
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
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.
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
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.
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.
@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.
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.
@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.
Hi @dceejay, just saw that there is again a new UI node (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...
@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-nodehere
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.
