Betrifft neue Dokumentation

OliverIO

Hier gibt es eine Vorschlag, der aber nicht wirklich von github angenommen wurde.
https://github.com/github/markup/issues/899

Benamung wäre dann
README.md = default english
README.de.md = deutsch
README.fr.md = französisch
usw

Homoran

@OliverIO

Im Moment halten wir noch alles unter iobroker.docs gemäß dieser Struktur:

https://github.com/ioBroker/ioBroker.docs/tree/master/docs

Für die final geplante Unterbringung der Adapterreferenz im Readme der Adapterrepos haben wir noch keine endgültige Entscheidung getroffen.

paul53

@Homoran Ein erster PR für Grundlagen / States und Datenpunkte ist erstellt.

paul53

@Homoran Wofür ist der Punkt Grundlagen / Funktionen gedacht ?

Homoran

@paul53
Danke!!

Aber du bist teilweise zu schnell

Ich wollte gerade in dem oberen Bereich das Menü eventuell noch umgestalten.
Da sind wir gerade in der Diskussion.
Einige Menüpunkte wurden schon vor einiger Zeit erstellt und wir wissen nicht mehr weshalb ;-)

Kann sein, dass es aus den enums: $functions$ kam

Homoran

@Zer0x sagte in ioBroker Installation via cURL nicht möglich:

sind nur teilweise leer.

Was fehlt denn an der verlinkten Anleitung?

BBTown

@Homoran ich habe die Installationsanleitung nicht über die Menustruktur finden können

Homoran

@BBTown

BBTown

@Homoran
Installation - Inroduction -> Platzhalter
Installation - Hardware -> Platzhalter
Installation - Fertigimages - Installation -> Platzhalter
Installation - Virtualisierungsplattformen - Installation -> Platzhalter
Installation - manuelle Installtion - Installation -> Platzhalter

Du glaubst ernsthaft, dass dann noch jemand weiter klickt?

JETZT käme ein Treffer:
Installation - manuelle Installation - Linux-> Doku

Dann gehts es wieder weiter mit:
Installation - Softwareupdates - Installation -> Platzhalter

Bei aller Liebe ... das ist Wahnsinn und frustrierend
Kannst Du die "Platzhalter" nicht "ausgrauen", "abschwächen", vor allem aber HINTEN ANSTELLEN und nicht vornewege nur Platzhalter zu haben bis mal irgend eine Doku wirklich verfügbar ist?

Sorry, ich weiss, dass hier viel Mühe und Engagement drinnen steckt, aber so verschrickt man doch jeden suchenden

Homoran

@BBTown

Ich hätte auch nichts dagegen wenn du je eine Anleitung für Docker, Proxmox, Mac und sonst noch was schreibst und als Pullrequest anbietest.
siehe auch: https://forum.iobroker.net/topic/22994/neue-dokumentation

Das würde die leeren Felder schneller füllen.

Leider ist es bei dem jetzigen System nicht ganz so einfach das Menü zu verändern. Dieses musste daher ganz zu Beginn geschrieben werden.
Leider bin ich schon eine ganze Zeitlang krank.

Auch wenn ich von der Intensivstation noch mit dem Handy tippe, klappt es mit der Doku leider nicht ganz so gut

BBTown

@Homoran Du weißt hoffentlich, dass ich dich nicht angreifen wollte, lediglich aufzeigen weshalb auch ich nicht fündig wurde ...

Ich wünsche Dir gute Besserung!!
Ich weiß Dein (Euer) Engagament wirklich zu schätzen!!

... ich würde dir das Handy ja wegnehmen, wenn ich dort etwas zu sagen hätte ;-)

Homoran

@BBTown sagte in Betrifft neue Dokumentation:

Du weißt hoffentlich, dass ich dich nicht angreifen wollte

Ja, aber es ärgert mich selber, dass ich da nicht weiterkomme :cry:

@BBTown sagte in Betrifft neue Dokumentation:

ich würde dir das Handy ja wegnehmen,

Das wirst du schön bleiben lassen, was soll ich sonst den ganzen Tag machen.
Aber wenn ich statt einen Link für ein Image zu schicken, das Image runterlade, ist meine Datenrate eh weg.

BTT:
Wie in dem verlinkten Thread geschrieben wird die Doku automatisch generiert.
Damit das funktioniert muss die Struktur vorher existieren.

Ein "ausgrauen" macht es IMHO nicht unbedingt übersichtlicher.

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! :joy: )
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 :scream: 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". :confused: