Formelle Gesichtspunkte zur Doku

[Homoran]

Ich wollte schon länger hierzu etwas schreiben, hab aber noch nicht alles zusammen.
Jetzt kam der Post von @Alcalzone im nodejs-Thread

@alcalzone sagte in Doku node.js Update:

Darüber hinaus habe ich einen großen Wunsch: Konsistenz

• Alle Dateipfade etc. bitte immer als Inline-Code formatieren. Die sind mal unformatiert, mal kursiv, mal anders formatiert, ... Das gleiche gilt für Befehle, Benutzernamen, etc.
• Befehle zum Ausführen bitte immer als Code-Blocks formatieren, damit man sie einfach kopieren kann:
• Das Programm heißt Node.js, nicht nodejs (das ist der alte Befehlsname), nicht node.js, nicht node (das ist der aktuelle Befehlsname)

Das wollte ich jetzt als Anlass nehmen.
Das wichtigste steht da schon drin, zusätzlich fällt mir im Moment nur noch ein Thema ein. Sollte Alzheimer es zulassen und die anderen Punkte noch wiederkommen, füge ich sie hier noch an.

Anrede in den Artikeln

Bitte unterlasst (versucht es zumindest) jegliche Art persönliche Anreden

Anstelle von Dazu klickt ihr dann auf den Button 'HolMichDerGeier' sollte eine allgemeine Formulierung wie Durch den Klick auf den Button "HolMichDerGeier" wird.... oder eine ähnliche inhaltlich passende Variante verwendet werden

Dadurch braucht man sich auch keine Gedanken über die Art der Anrede zu machen

[Feuersturm]

In der aktuellen Doku gibt es schon einen Styleguide welcher ebenfalls hilfreich ist: https://www.iobroker.net/#de/documentation/community/styleguidedoc.md

Dort ist ebenfalls eine Hilfestellung zu Markdown enthalten: https://www.iobroker.net/#de/documentation/community/docmarkdown.md

[Homoran]

@feuersturm sagte in Formelle Gesichtspunkte zur Doku:

welcher ebenfalls hilfreich ist

Ja, einiges davon muss selbst ich mehrfach lesen um halbwegs zu galuben ich hätte es verstanden, aber im allgemeinen passt es.

Kannst du mir sagen wo ich .editorconfig finde?

[Feuersturm]

@homoran sagte in Formelle Gesichtspunkte zur Doku:

Kannst du mir sagen wo ich .editorconfig finde?

Ich hab keine editorconfig für die Doku gefunden.

[AlCalzone]

@homoran sagte in Formelle Gesichtspunkte zur Doku:

Kannst du mir sagen wo ich .editorconfig finde?

Die müsste sich eigentlich im entsprechenden Repository finden... eigentlich.

[OliverIO]

@homoran

damit man nicht alles neu erfinden muss
https://opensource.com/article/20/3/documentation
https://medium.com/capital-one-tech/art-of-open-source-documentation-5b8b3f5b0ab

[Jey Cee]

Hier mal noch ein Vorschlag:
Aktuell wird nur das Datum hinterlegt wann die Seite das letzte mal Aktualisiert wurde.
Bei Themen die Versionsabhängig sind sollten die Versionen gut Sichtbar angegeben werden. Damit man Einordnen kann ob die Informationen der Seite für einen selbst zutreffend sind.

In der Form "Gültig für folgende Versionen" oder "Getestet mit folgenden Versionen"

[Homoran]

@jey-cee Auch wenn es hier wieder um Formalitäten geht, die Beamtendeutschlands würdig sind, so hatte ich vor Jahren so etwas vorgeschlagen.
Damals gab es noch einen "Steckbrief" als Header in den Doku-Seiten.

Auch der Ersteller sollte IMHO irgendwo drinstehen. Aber was, wenn später nur an einzelenen Stellen Änderungen durch jemand anderes durchgeführt werden.

Im Moment sollten wir zusehen, dass Content eingepflegt wird.
Jeder -auch du- kann dann PullRequests mit einer konstruktiven Änderung einbringen

Die Hürden sollten im Moment so niedrig wie möglich gehalten, und nur auf funtionsrelevante Dinge beschränkt bleiben, sonst wird es noch ewig Platzhalter und fehlende Inhalte geben