Documentation normalization

Core Development
1

I may be on a limb here, but I was cobbling something together;

Read all nodes in the node_modules folder and extract the help/documentation and create a unified /docs endpoint where it all comes together, eg:

image
image1794Ă—1454 291 KB

I found that the help text is not consistent. Some have descriptions, some don't. Some specify the inputs/outputs, others only have a single paragraph, or just markdown. Not easily parsable.

I can imagine that cannot be easily solved, but has there been any brainstorms how to tackle consistency ?

1 Like
2

We have had a style guide for help as part of the documentation for a long time - Node help style guide : Node-RED

So it is very much up to node author's to play their part.

An alternative would be to find a way to auto-generate that content, but that would still require node authors to do something to provide the raw content.

3

Sorry to be picky but those are not docs. They are help entries. There can be a big difference for any of the more complex nodes.

4

Again completely off-topic, but I call it whatever I want.

5

The concept of the Help sidebar was also for it to be a place that nodes could add longer-form docs to - and not have it just be docs for individual node types.

Is there interest in having that? Or should nodes link out to their own docs wherever they choose to host it on the internet? One concern would be more scope for inconsistent style and quality.

6

The sidebar really doesn't work for complex nodes since it is too limited as is the formatting. I'm not complaining of course, the formatting is fine for a help panel and totally useful for that. It is the right tool for the majority of nodes for sure.

Rightly or wrongly, I decided that it would be helpful to anyone who wanted to be offline to have the main documentation available locally and it was in the repo anyway so comes through with the installation. As we have a web-server to hand anyway, why not use it for fuller documentation about the node if the node warrants it.

I'd be totally happy for there to be a standard URL that could be optionally included in a node. I'd also be happy if it had some standards - though I think that is possibly a much harder ask and potentially quite a lot of work to come up with a standard. For my docs, you'll see that I chose to use Docsify because it lets you stick to simple Markdown with a single HTML page to do all the work. It also lets you expand into quite comprehensive markdown extensions such as incorporating various diagrams and some nice-to-haves such as note/warning/information panels. It also uses VueJS under the skin and so lets you add niceties such as using frontmatter data in the page display. (As a sidenote, I use the same code on our IT Standards document at work, just with a different style on it).

So I understand the concern about consistent style - though I might argue that for full docs, I'm not sure it matters so much? Again, though, I wouldn't mind as long as there was some flexibility to accommodate more complex documentation.

7

I was wondering if one could get away with just an object like;

{
  "node": {
    "description": "Some useful help text to introduce the node.",
    "input":{
      "type": "payload",
      "detail": "Accepts a string, object or array"
    },
    "output":{
      ...
    },
    "details": "Some more information about the node."
 }
}
8

This topic was automatically closed 14 days after the last reply. New replies are no longer allowed.