# Documentation normalization

**URL:** <https://discourse.nodered.org/t/documentation-normalization/76238>\
**Category:** Core Development\
**Created:** [7 March 2023 14:24 UTC](https://discourse.nodered.org/t/documentation-normalization/76238 "2023-03-07T14:24:20Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![bakman2](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bakman2/32/6207_2.png) [@bakman2](https://discourse.nodered.org/u/bakman2)\
**Post date:** [7 March 2023 14:24 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/1 "2023-03-07T14:24:20Z")

</div>

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](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/3X/8/8/88510cdd6fbf0a08349b4a87e2a503a6d07e72df.png)

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 ?

---

<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:** [7 March 2023 14:28 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/2 "2023-03-07T14:28:28Z")

</div>

> [@bakman2](#):
>
> I can imagine that cannot be easily solved, but has there been any brainstorms how to tackle consistency ?

We have had a style guide for help as part of the documentation for a long time - [Node help style guide : Node-RED](https://nodered.org/docs/creating-nodes/help-style-guide)

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.

---

<div class="post-metadata">

**Author:** ![TotallyInformation](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/totallyinformation/32/31_2.png) [@TotallyInformation](https://discourse.nodered.org/u/TotallyInformation)\
**Post date:** [7 March 2023 20:02 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/3 "2023-03-07T20:02:17Z")

</div>

> [@bakman2](#):
>
> unified /docs endpoint

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.

---

<div class="post-metadata">

**Author:** ![bakman2](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bakman2/32/6207_2.png) [@bakman2](https://discourse.nodered.org/u/bakman2)\
**Post date:** [7 March 2023 20:28 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/4 "2023-03-07T20:28:44Z")

</div>

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

---

<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:** [7 March 2023 20:41 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/5 "2023-03-07T20:41:01Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![TotallyInformation](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/totallyinformation/32/31_2.png) [@TotallyInformation](https://discourse.nodered.org/u/TotallyInformation)\
**Post date:** [7 March 2023 21:05 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/6 "2023-03-07T21:05:22Z")

</div>

> [@knolleary](#):
>
> 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.

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.

---

<div class="post-metadata">

**Author:** ![bakman2](https://sea2.discourse-cdn.com/flex026/user_avatar/discourse.nodered.org/bakman2/32/6207_2.png) [@bakman2](https://discourse.nodered.org/u/bakman2)\
**Post date:** [7 March 2023 22:35 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/7 "2023-03-07T22:35:28Z")

</div>

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

```auto
{
  "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."
 }
}

```

---

<div class="post-metadata">

**Author:** ![system](https://us1.discourse-cdn.com/flex026/uploads/nodered/original/1X/d073cd938eafa2e558d7c2cd59003b3ef4963033.png) [@system](https://discourse.nodered.org/u/system)\
**Post date:** [21 March 2023 22:35 UTC](https://discourse.nodered.org/t/documentation-normalization/76238/8 "2023-03-21T22:35:48Z")

</div>

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