Betrifft neue Dokumentation

[Jan1]

@Homoran
Ich hatte ja auch schon ein Mecker Thread geöffnet, weil die neue Doku zu derzeit sehr unbrachbar war und eine halbwegs logische Suche für mich nur auf leeren Seiten endete.
Mittlerweile ist das ja besser, so ganz glücklich bin ich aber auch noch nicht. Hab da aber Vertrauen, dass das selbst vom Krankenbett gelöst wird.
Deshalb auch von mir Gute Besserung.

[Homoran]

@Jan1

Danke!
Gottseidank bin ich im Moment auf freiem Fuss und konnte mich vor der nächsten OP erst einmal drücken

Bald kann ich auch wieder (länger) am PC sitzen , dann hoffe ich, dass sich im letzten Jahr nicht zu viel Arbeit zu Hause angessammelt hat und ich wieder in die vollen starten kann.

Mit Meckern, wenn es denn produktiv ist, habe ich überhaupt keine Probleme.

[foxriver76]

@OliverIO sagte in Betrifft neue Dokumentation:

Was wäre die Namenskonvention, um selbst eine deutsche Übersetzung auf github bereitzustellen, so dass es von dort aus dann übernommen werden kann?

Wird in der io-package.json festgelegt, z. B. hier für Deutsch.

Edit: Wird wohl noch nicht angezogen.

[Homoran]

@BBTown

Das hat mir jetzt keine Ruhe gelassen und ich habe mir das gerade nochmal angesehen:

Fang ich mal hinten an:
@BBTown sagte in Betrifft neue Dokumentation:

vor allem aber HINTEN ANSTELLEN

genau das geht nicht! (auch wenn ich das mal nicht als anschreien interpretiere! )
Die Menüstruktur muss vorher stehen, auch weil es in mehreren Sprachen die gleiche bleiben muss und je Sprache verschiedene User daran arbeiten (sollen).

@BBTown sagte in Betrifft neue Dokumentation:

Installation - Inroduction -> Platzhalter
Installation - Hardware -> Platzhalter

Ich weiß gar nicht, was da mehr als ein, zwei Sätze rein soll. Das wird wohl mit der Zeit (Open Source sei Dank) wachsen.

Installation - Fertigimages - Installation -> Platzhalter
Auch das wird schon etwas kniffelig.
Es wird keine allgemeingültige Seite für ALLE Images geben können.

Daher könnte man diese Einträge wieder entfernen.

Das wird auch an anderen STellen noch passieren können. Wenn man eine Idee hat, wie die Doku aufgebaut sein könnte, und sie anschließend mit Inhalt füllen will, erkennt man oft erst dann, dass es so nicht gehen kann.
Daher sind wir ja auch über konstruktives Feedback so froh.

Installation - Virtualisierungsplattformen - Installation -> Platzhalter

Hier wird es jetzt speziell:
Wie du vielleicht gesehen hast geht der Link hinter dem Menüpunkt nach
https://www.iobroker.net/#de/documentation/install/docker.md

ebenso wie der Link hinter:

Installation - manuelle Installtion - Installation -> Platzhalter

zu
https://www.iobroker.net/#de/documentation/install/macos.md

geht.

Ich habe weder eine Docker-Installation, wie auch keinen Apfel, noch kenne ich mich (bis jetzt) damit aus.

Alles was ich in der bisherigen Doku geschrieben habe, habe ich selbst genau so durchgeführt und solange getestet, bis es reproduzierbar so lief.

Die Installation auf dem Mac war damals schon ein "Gastbeitrag" und das Geschrei war groß, wie man so etwas veröffentlichen könne, das nicht funktioniere.
Zum Zeitpunkt der Veröffentlichung haben es mehrere User erfolgreich damit installieren können. In zwischen hatte OS X wohl einige Updates und es klappte nicht mehr.

Wie soll man mit so etwas verfahren, was man selber nicht testen kann?

Also bleibt so etwas "erst einmal" liegen und man hofft, dass durch den verlinkten Aufruf mit dem Appell an den Open Source Community Gedanken sich jemand bereit erklärt.

P u s t e k u c h e n !!

Und deswegen steht da auch nicht nur Platzhalter! sondern auch:

Hilf mit bei ioBroker und erweitere diesen Artikel.
Bitte beachte den ioBroker Style Guide, damit die Änderungen einfacher übernommen werden können.

[Jey Cee]

@Homoran sagte in Betrifft neue Dokumentation:

Zum Zeitpunkt der Veröffentlichung haben es mehrere User erfolgreich damit installieren können. In zwischen hatte OS X wohl einige Updates und es klappte nicht mehr.

An dem Punkt kann man einhaken, mit dem letzten Bearbeitungsdatum kann man schon sehen wie alt mindestens eine Anleitung ist.
Um das noch genauer zu machen kann man Versionen von OS, ioBroker usw. angeben.

[Homoran]

@Jey-Cee Deswegen haben wir ja jetzt das Erstellungs- Änderungsdatum mit drin.
Leider nicht ganz oben, sondern unter dem gesamten Text

[BBTown]

@Homoran es war natürlich kein Anschreien, sondern ein Hervorheben

Nun habe ich ggf. für Verwirrung gestiftet.
Es ging gar nicht um die einzelnen Punkte oder deren Sinnhaftigkeit.
Ich bin vorgegangen wie womöglich eine Reihe von Usern das machen würden.
Ich gehe in den Bereich Installation und klicke mich nun der Reihe nach durch.
Und finde im Grunde rein gar nichts ... der Punkt den ich eigentlich finden wollte befand sich unter .x/x/x/Linux
Aber da hatte ich dann schon aufgegeben; ich hatte nicht mehr erwartet unter irgend einen Punkt noch etwas zu finden.

Das war dann Ausgangspunkt meiner "Anregung" ob man ggf. optisch helfen kann, wo es sich lohnt nachzuschauen und wo ggf. derzeit noch nicht.

Angeregt durch dein "Mach mit" dachte ich dann, ich gehe mal eben auf die die "Introduction Seite" der Rubrik "Installation" und schreibe da rein "Derzeit lohnt sich vor allem der Blick in den Bereich "x/x/x/Linux", da die Seiten noch im Aufbau sind ... quasi als Anleitung wo bereits Informationen sind (Eine Doku für die Doku )

... ich war weder in der Lage einen Link gemäß der Vorgaben einzubauen, noch lies sich das ganze Speichern ... da hatte ich wieder Frust und hab "Schulterzuckend aufgegeben".

[Homoran]

@BBTown sagte in Betrifft neue Dokumentation:

Ich bin vorgegangen wie womöglich eine Reihe von Usern das machen würden.

So habe ich das auch gelesen!
Ich verstehe dich doch!

@BBTown sagte in Betrifft neue Dokumentation:

Eine Doku für die Doku

gibt es :
https://www.iobroker.net/#de/documentation/intro/README.md

Da sollte ich es vielleicht gaaanz oben nochmal deutlich machen, dass die Doku ein "work in progress" ist.

@BBTown sagte in Betrifft neue Dokumentation:

... ich war weder in der Lage einen Link gemäß der Vorgaben einzubauen,

Woran hat es da gescheitert?
Das müssen wir dann im Unterstützer-HowTo besser erklären.

@BBTown sagte in Betrifft neue Dokumentation:

noch lies sich das ganze Speichern ..

C&P und dann als Pullrequest.
Sollte auch irgendwo stehen. Wenn NIcht, oder nicht deutlich genug, dann muss das auch geändert werden.

Danke für das (und das kommende) Feedback!

[BBTown]

@Homoran kann die Struktur denn leicht erweitert werden?
Was würdet Ihr davon halten bspw. unter FAQ (oder als eigenen Bereich) ein "Glossar" mit aufzunehmen.

Vielleicht kann man hier - ähnlich einem Wikipedia - dem Einen oder andern User auch nahebringen was was ist ...

• Github -> "von Github installieren" - was ist damit eigentlich gemeint
• Proxmox -> "Ein schlankes Linux basiertes Betriebssystems zur Verwaltung von VMs und Containern"
• Shelly -> "Shelly ist ein Anbieter von Smarthome Komponenten ähnlich HomeMatic oder x, y"
  usw.

Darüber könnten ggf. als Ergänzung schnelle Informationen und Wissen vermittelt/aufgebaut werden als sofort einen "Artikel" über etwas zu verfassen (?!?)

[Homoran]

@BBTown sagte in Betrifft neue Dokumentation:

kann die Struktur denn leicht erweitert werden?

nicht wirklich - aber ich werde mein bestes machen

@BBTown sagte in Betrifft neue Dokumentation:

Was würdet Ihr davon halten bspw. unter FAQ (oder als eigenen Bereich) ein "Glossar" mit aufzunehmen.

Du wirst lachen, das war sogar eines der ersten Aktionen, als wir vor Jahren diese Struktur anfangen wollten.
Muss nur suchen, wo die bei dem Umzug abgeblieben ist.
Hier der Entwurf:
https://github.com/ioBroker/ioBroker.docs/blob/master/archive/src/de/0_GLOSSARY.md