This is really a Q for @knolleary et al. The background is that I am an experienced developer / sysadmin with no karma on this project, but who now seems to use Node-RED for personal use. As with many FLOSS projects, the documentation is extremely thin in many areas as a result of resourcing limits and priorities. This doesn't bother me too much personally as I just go through the github node-red and node.js module sources to work out how to do what I want.
However I sometimes think that general users might find some of these points sufficiently useful to merit adding to the documentation set. So what is the preferred way of doing this? I see that Nick points would-be contributors to this forum. Do you want one topic per putative change, and what is the convention for tagging such threads?
I will use one topic area by way of example: the MySQL node. I feel that it would help general users if some richer examples were included in the documentation that cover the following as these can considerably simplify the companion Function nodes:
A query can contain multiple SELECT statements, and the returned payload is an array of RS
Multi-row INSERT. You can insert multiple rows into a table with a single MySQL node call using the VALUES ? clause if the BV is an array of row arrays. A bit counter-intuitive, but very fast.
Using a MySQL node as a loopback companion to a function so that the function can call MySQL many times.
Node-RED, being a FLOSS project, welcomes contributions from its whole community.
If you've an experience to share, I'm sure your PR would be highly appreciated - especially when it improves the documentation!
A quick question (maybe a stupid one):
I was trying to share a "how-to" document which I thought would be useful to the community. However, I was not able to upload it to the forum (it is a Word document, and the upload rejects this doc type).
So, how do I upload such documents?
The de-facto "standard" format for documentation seems to be Markdown - which is basically plain text with a number of "magic" tokens that are understood as format identifiers.
In fact, when posting here, you're creating Markdown type document fragments. Thus - a propper format to create & exchange documentation is/could be Markdown.
The other half of your question: Where should you post those documents?
At least two options:
Post it here. As topics age out, it will be - after some time - quite difficult to re-discover your post though.
Create a pull request (PR) against a repository at GitHub. This allows to integrate your contribution in the source of a package - and helps to make it easier accessible to those who use the package.
As Ralph says, Markdown is the gold standard for most open source documentation. Much easier to use generally than the Office formats.
VScode has lots of Markdown helper extensions including live previews. But if you want a more WYSIWYG type experience, the best I've found is Typora which I've actually paid for. Knowledgebase type tools such as Obsidian are also great because they too use Markdown.
If you want to put things on the forum, the FAQ section might be your best bet. You can, of course, use the Flows site where you can upload example flows and accompanying information (also Markdown).
Then there is the often overlooked Node-RED Cookbook which has its own GitHub repo and takes PR's.
And, of course, if your suggestions relate to a specific node, you will need to find the documentation for that node and submit a PR - usually after a discussion with the author.
And if all else fails, you could post to your own blog if you have one. If you don't have one, a community such as DEV Community might be useful.
In the case of well annotated example flows relating to a single node, they could also usefully be bundled as part of the node installation. Perhaps this is appropriate for the OP's MySQL examples. It would require a PR I guess.
An example:
I don't think the Node-red cookbook is a very valuable resource, but it could be if it was edited and easy to submit content for.
Share your Projects on the forum is much more vibrant, of course it's interactive.
I have worked on a few open source collaborative developments in the past, but I am no longer interested in painful project politics or status. (I am probably older than most of your dads ). It's just that I now use node-red for personal uses, and so I don't mind contributing efficiently where relevant in a way that might help newbies.
The project maintains some nodes within its core canon because they are too important to the project for it to devolve change control to a 3rd party. IMO, the online documentation for most of these is appropriate to their use. The three core nodes that I use a lot, but for which the documentation could really do with improving are the Function and HTTP variants. In the case of 3rd party-maintained node MySQL is a case in point. For all, I ended up going through the project source in github and the node.js source modules that they wrapped to work out how to do what I needed. Doing this sort of reverse engineering requires a level of coding expertise and github familiarity that is probably beyond 90% of Node-RED users, so it seems sensible help distill some of these gaps into the online documentation to make this knowledge more generally available.
What I am used to doing in a github life cycle is to raise an issue and draft a pull request for a suggested change, however the Contributing Guidelines state that I should first raise the issue as a topic here and this is what I am doing.
So looking at these modules:
HTTP XX. The documentation is reasonably complete, but there are important usage constraints especially with HTTP In .. HTTP Response that aren't discussed, but are covered in the Cookbook/HTTP Recipes. The access path to these Recipes isn't clear, so my suggestion is that the HTTP nodes should include a link / reference to HTTP Recipes for further information. In the case of these nodes, Nick seems to be the main committer and so he is the one (according to his own guides) should be the one I should be discussing this with, or do I just go with the normal Github lifecycle and raise the Issue + PR?
Function. My real issue with the function documentation is that this node is very rich in nature but that the basic function documentation can't go into this without losing the majority of readers, so what is really needed are a few cookbook style Articles in the Cookbooks section to cover this sort of my detailed content. For example, whilst most of my function nodes are simple message in→out groomers, I started pushing this envelope by using loopback helper HTTP and MySQL nodes, until I decided that this was becoming an abuse of the Node-RED flow paradigm by adding too much complexity; what I really needed for this type of processing was a standard async node.js function, and the penny dropped that there was nothing stopping me doing this within Node-RED function. A few decent Cookbook recipes would have helped here.
MySQL I realise that this is in the node-red-nodes repository rather than core, so does that mean I should just raise any issues directly with the maintainer via Github, rather than discuss them here?
Hi @terrye, I look after the mysql node - and have just retired - so unless you are over 90 then you won't be older than my dad the node-red-nodes project is still under the main Node-RED organisation on github, so yes discussing here is appropriate. And yes - any docs improvements - preferably via pull request - would be gratefully accepted, as would examples.
The reason we want discussion here first is mainly for code PRs. We used to get quite a few "drive by" pull requests where folk would create a wonderful (to them) feature and spend hours coding, and just drop it in issues and then wonder why it wasn't just accepted when it didn't meet the aims or direction of the project, or maybe dragged in loads of extra libraries 95% of users would never need etc, but yet the core team would then have to maintain... such is Open Source of course... but net is we like to give people a chance to propose something first so we can discuss more widely and maybe tweak it enhance it before they write too much code. Obviously this is much less critical for documentation, but still probably sensible.
so yes please - your contributions would be most welcome.
FWIW - re HTTP, yes a link to Node-RED Cookbook : Node-RED would seem appropriate, and likewise some Function node recipes would be great - note the intention for the cookbook was not to be node specific - but more use case based "how do I.... " do an async function - etc but yes they are grouped by the main node in question like http, mqtt etc
You lucky so-and-so! Still a few years to go yet for me. On the horizon though.
However, what would be great if any core-node changes are being made would be to standardise a link to the appropriate place(s) in the documentation at the top of the node's help panel.
What might also be super helpful would be at the end of the help to have a link to the appropriate area of the Node-RED repo's. The way that the repos are organised make it REALLY hard to work out where you need to go - even for those of us who've been around a long time.
The original intent of Node-RED was that nodes should be simple and clear enough to not need complex docs and to be able to run (and develop) without need of internet.
Of course over time nodes have got more complex, as have user requirements and expectations (and range of abilities). So yes I can’t see a problem with adding some links where necessary, but I’d hope most core nodes should not require it.
(And of course then there is the issue of translation and maintenance)
I was 70 this year; I started programming at 14, and by the time I took a year out working up as a programmer to help save up for Uni, I was competent in 3 high level languages and 2 assemblers so definitely not old enough to be your dad though Nick O’Leary looks about my son's age
Re MySQL My main two suggestions would be to include some patterns the MySQL users might find useful, but let's have this dialogue on an MySQL issue.
If you are happy with what I propose here then I can cover other point on later posts here.
Ohh I'm pre-historic!!! WooHoo, I can't wait till I tell my grandkids. I turned 70 this past June but, I believe you are a young as you feel and I still feel like a kid!!
I'm not going to tell you how old I am - just to say I'm 7-years older than you ( )
Oh drat, just realised that younger people can still do the maths!!
). It's just that I now use node-red for personal uses, and so I don't mind contributing efficiently where relevant in a way that might help newbies.
the node-red-nodes project is still under the main Node-RED organisation on github, so yes discussing here is appropriate. And yes - any docs improvements - preferably via pull request - would be gratefully accepted, as would examples.
- etc but yes they are grouped by the main node in question like http, mqtt etc
though Nick O’Leary looks about my son's age 
)