Hallo Rainer,
ich verstehe Nordlicht sehr gut und finde es super, dass du dir darüber Gedanken machst.
ioBroker entwickelt sich seit Beginn mit großen Schritten weiter und auch die Doku hat sich durch eure ständige Arbeit wesentlich verbessert.
Was ihr da leistet, ist bemerkenswert.
Ein Anfänger kann mit Tutorials im Internet oder mit Literatur JS erlernen, doch bezieht sich das Meiste davon auf Webseiten-Programmierung mit HTML und CSS.
All das wird in ioBroker auch eingesetzt, aber nur selten auf die gleiche Art und Weise, wie es die Literatur erklärt. Jedenfalls fehlt dem Anfänger hier noch das Transfervermögen. Ich selbst stehe da irgendwo in der Mitte dieser Phase 
Speziell beim JavaScript-Adapter würde ich mir zu den Funktionen noch mehr Details mit Erklärungen wünschen.
Trotz des gesamten Umfanges sind die einzelnen Beschreibungen extrem kompakt gehalten.
Es ist vielmehr ein Nachschlagewerk für erfahrene Anwender, als eine Beschreibung für Einsteiger.
Als Beispiel und zur Erklärung möchte ich die "on"-Funktion nennen, mit deren Parametern ich mich zur Zeit intensiver auseinandersetze.
Nehmen wir davon mal den ersten Parameter:
` > You can use following parameters to specify the trigger:
parameter______type/value _____description
–---------------------------------------------------------------------------
logic___________string__________"and" or "or" logic to combine the conditions (default: "and") `
Hierzu ergaben sich folgende Fragen:
1. Lassen sich beliebig viele Parameter verunden bzw. verodern?
2. Kann "and" mit "or" kombiniert werden? z.B. (Licht1 and Licht2) or (Licht3 and Licht4)
3. Wenn ja, wie sieht die Syntax dazu aus?
Wer genug Erfahrung hat, würde die Fragen so beantworten
1. Es wurden keine Grenzen angegeben, deshalb können beliebig viele Parameter verwendet werden.
2. Da steht "and" or "or", also geht nur eines von beiden.
3. Geht nicht, wegen Antwort von Frage 2.
Als weiteres Beispiel nehme ich einen Ausschnitt aus dem diskutierten Skript von Nordlicht:
> on({id: bwm, val: true}, function (obj) { // Trigger auslösen Bei val steht In der Beschreibung: New value must be equal to given one.
Als Anfänger bin ich davon ausgegangen, dass sich ein neuer Wert von einem alten Wert im Wert unterscheiden muss, sonst ist es kein neuer Wert.
Daher hätte ich erwartet, dass der Trigger nur auslöst, wenn der Wert des bwm von "false" auf "true" wechselt.
Das tut er sogar, aber er löst auch aus, wenn der "Zeitstempel" des Wertes aktualisiert wird, weil dann der Wert "true" durch ein neues "true" ersetzt wurde.
Im Skript von Nordlicht hat das keine Auswirkungen, da er noch eine Sperrvariabale verwendet, aber in einem anderen Skript sorgt es erstmal für Verwirrung.
Zumindest zu dem zweiten Beispiel gab es schon einige Diskussionen, die mit einer etwas umfangreicheren Doku wahrscheinlich nicht entstanden wären.
Die Doku ist das wichtigste Instrument, um neue User bei den ersten Schritten mit ioBroker zu begleiten und um den Spaß an der Sache aufrechtzuerhalten.
Ich möchte in Bezug auf den JS-Adapter vorschlagen, die Funktionen in der bestehenden GitHubDoku mit weiterführenden Links zu Detailbeschreibungen zu versehen.
Die verlinkten Seiten beschreiben dann die gewählte Funktion noch mal genauer (evtl. in Denglisch) und zeigen weitere Beispiele (Codeschnipsel) mit Kommentierung auf.
Man könnte das mit den Linux Man-Pages vergleichen, die man dann aufruft, wenn die Kurz-Referenz des –help-Parameters nicht ausreicht.
Grüße
