Pro: Argumente im Tag bei Prüfung durch commandref_join.pl

Begonnen von Ellert, 30 Dezember 2015, 17:46:30

Vorheriges Thema - Nächstes Thema

herrmannj

Ja, ist auch ein gültiger Standpunkt.

Vielleicht könnte man neben EN und DE einen optionalen dritten Part einführen der für "erweiterte Doku" zuständig ist. Der ist per default unsichtbar und man kann ihn einblenden?

vg
joerg

Damian

Zitat von: rudolfkoenig am 01 Januar 2016, 14:06:47
DOIF ist aus mehreren Gruenden kein gutes Beispiel fuer Commandref Eintraege, die wichtigsten sind mAn, dass die Zielgruppe von DOIF keine Entwickler sind, und dass der Commandref nicht fuer Beschreibung von Programmiersprachen gedacht ist. Ich wuerde eine Doku mit solchen Inhalt eher im Wiki oder als PDF erwarten.
Ich habe kein Problem die ersten paar Zeilen der einführenden Doku in der commandref zu belassen, um dann mit einem Mausklick auf weitere Seiten zu kommen. Diese Anforderung an die Commandref ist nicht neu. Ich habe allerdings keine Muße, wie du sicherlich auch, mehrere Dokumentationsquellen umständlich zu pflegen.
Programmierte FHEM-Module: DOIF-FHEM, DOIF-Perl, DOIF-uiTable, THRESHOLD, FHEM-Befehl: IF

viegener

Ich finde es nachwievor entscheidend eine einfach durchsuchbare commandref zu haben (direkt im Browser ohne Google zu bemühen), bei der ich nicht nur nach Befehlen sondern auch Attributen und weiteren Benennungen suchen kann. Gerade wenn man wie ich erst relativ kurz dabei ist, nutze ich das nachwievor fast täglich! Klar liest man regelmässig auch mal "nur" die Doku zu einem einzelnen Device, aber dafür gibt es ja die direkt Möglichkeit im FHEMWeb beim Device.

Wenn ausgelagert wird, dann sollte trotzdem in der Commandref eine vollständige Dokumentation der Optionen enthalten bleiben.

Und ja, bitte die Hürde für Doku für die Entwickler nicht erhöhen!

Kein Support über PM - Anfragen gerne im Forum - Damit auch andere profitieren und helfen können

Ellert

#18
Ich wollte eigentlich nur die vertikale Ausrichtung der Tabellenzeile weiterhin selbsbestimmt ermöglicht haben ;).

Die hier vorgetragenen Standpunkte möchte ich mit meiner Anwender- und Einsteigersicht ergänzen.
Mir haben die erläuternden Beispiele zum DOIF soweit geholfen, dass eine aktive Hilfesuche im Forum nicht notwendig war. Ich war überrascht, wie anwenderfreundlich die Dokumentation gestaltet ist, aus ihr spricht das Interesse die Anwendung auch zu vermitteln.

Das DOIF ist gewachsen, die Doku auch. Ich benötige auch nicht mehr alle Beispiele und wollte einen schnelleren Zugriff auf die Abschnitte, deshalb habe ich Inhaltsverzeichnis und die Kurzreferenz vorgeschlagen, bestimmt noch nicht perfekt.

Eine Commandref zum Durchsuchen begrüsse  ich, jetzt sind es ja noch zwei (DE|EN), bei etwa 97% Verbreitung im deutschsprachigen Raum.

Die Commandref wie eine Manpage zu gestalten ist sicher sinnvoll. Ich habe mir ein paar Spezifikationen angesehen, hier mal ein Beispiel http://pubs.opengroup.org/onlinepubs/9699919799/utilities/at.html
Aufgefallen ist mir, dass die Struktur der Manpages auch einen Abschnitt "Examples" enthält oder wie im Beispiel auch "Application Usage" usw.

Damit wären erläuternde Beispiele nicht nur erlaubt, sondern systematisch erwünscht.