Die Neo-Dokumentation und -Homepage mit MkDocs.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 

6.5 KiB

Beitragen

Treiber-Entwicklung

Die Neo-Treiber sind für die großen drei Betriebssysteme seit Jahren stabil. Dennoch ist der eine oder andere Bug vorhanden, oder es müssen Anpassungen an neue Betriebssystem-Versionen her. Wenn du mitmachen möchtest oder dich für die Entwicklung interessierst, schau dich im „Beitragen“-Bereich um oder schau im Neo-Chat vorbei.

Wir nutzen Gitea zur Code-Verwaltung. Das Repository auf Github ist lediglich ein Mirror. Ist ein Github-Account vorhanden, kann man sich damit auch bei unserem Gitea registrieren und anmelden.

Bugreports, Fragen, Vorschläge

Wenn Neo nicht so will wie erwartet oder es Fragen / Vorschläge gibt, kannst Du im Gitea ein Issue anlegen. Oder du meldest dich auf einem der anderen Wege bei uns.

Dokumentation

Einer der Artikel ist nicht genau genug, oder gar falsch? Es gibt fehlende Informationen? Trag sie nach: auf jedem Artikel findest Du oben rechts neben dem Titel einen Edit-Button. Du brauchst nur einen Account beim Gitea (siehe oben) und kannst dann die Seite editieren.

Besonders komfortabel ist die Bearbeitung, wenn du im Gitea-„WikiEditors“-Team bist. Dann kannst du in Gitea direkt oben rechts auf den Bearbeiten-Button gehen und in dem Repository einen neuen Branch mit Pull-Request mit deinen Änderungen erstellen. Ansonsten kannst du das Repository aber auch forken und dann einen Pull-Request stellen. Wir fügen dich gerne zum „WikiEditors“-Team hinzu, wende dich einfach an uns.

Syntax

Diese Dokumentation wird mittels MkDocs erstellt. Eine kurze Übersicht, wie man eigene Seiten definiert und füllt, findet sich hier.

MkDocs verwendet Github Flavored Markdown. Alle Dateien werden in einem Repository gehalten. Dadurch können z.B. Graphiken als interne Links auf Dateien eingebunden werden.

Zusätzlich stehen zur Verfügung:

Solltest du eine Erweiterung benötigen, die nicht aufgeführt ist, schreib uns dazu. Wenn sie nützlich ist, können wir sie hinzufügen.

Externe Links zu anderen Seiten oder extern eingebundenen Bildern (auch als Image-Links) werden mit voller URL (https://…) absolut angegeben.

Interne Links zu anderen Markdown-Seiten oder sonstigen Dateien im Wiki werden relativ angegeben. Der Vorteil besteht darin, dass MkDocs bei der Erstellung der Site alle relativen Links auf Vorhandensein überprüft. So können eventuell tote oder falsche Links nach Umbauarbeiten direkt gefunden werden.

Ankerlinks auf Überschriften funktionieren bei relativen wie absoluten Links identisch. An den Link wird # sowie eine Repräsentation des Überschriftentitels angehängt. Dabei werden die Worte kleingeschrieben und mit Bindestrichen verbunden, sowie Umlaute ohne Punkte geschrieben.

??? example "Beispiele" - (Linux.md) verweist auf die Seite „Linux“, die im selben Verzeichnis wie die aktuelle Seite liegt - (images/image.jpg) verweist auf ein Bild im Unterverzeichnis images parallel zur aktuellen Seite - (../Downloads/installation.md) verweist auf die Datei mit der Seite „Installation“, die im parallelen Verzeichnis „Downloads“ liegt - (../Lernen/vorteile.md#wichtige-kriterien) verweist auf die Seite in der Datei vorteile.md, die im parallelen Verzeichnis „Lernen“ liegt, und innerhalb der Seite auf den Überschriften-Anker für „Wichtige Kriterien“. - (#manuelle-installation) verweist auf den Überschriften-Anker „Manuelle Installation“ innerhalb desselben Dokuments.

Richtlinien

Für die Bearbeitung, aber insbesondere Erstellung neuer Seiten, sind einige Richtlinien zu beachten, um einen einheitlichen Stil zu gewährleisten.

Allgemeines

Innerhalb eines Artikels können Kommentare mit der Syntax von HTML-Kommentaren (eingeschlossen in <!-- und -->) hinzugefügt werden, da so mehr Hinweise hinterlassen werden können, die zudem den Lesefluss nicht stören.

  • Keine mehrfachen Links auf einer Seite – ein Begriff sollte nur bei seiner ersten Erwähnung verlinkt werden (dies ist in der Wikipedia auch so geregelt).
  • Möglichst keine Links vom Benutzerhandbuch in den Entwicklerbereich
  • Spezialthemen nicht auf wichtigen Hauptseiten verlinken, um insbesondere Einsteiger nicht abzuschrecken
  • Nicht mit mit allzu vielen Links verwirren: keine Links setzen, wo sie unnötig sind

Aber auch nicht vergessen: ein Wiki ist kein Papier und Links sind ein elementarer Bestandteil. Der Anwender kann und soll schließlich selbst entscheiden, was er anklickt.

Verwenden von Admonitions

Admonitions zeichnen einzelne Textabschnitte gesondert aus, indem sie mit einer eigenen Überschrift und einer vordefinierten Hintergrundfarbe gekennzeichnet werden. Sinnvoll ist dies bei vertiefenden Informationen, bei besonders wichtigen Details, bei zu beachtenden Dingen und potentiellen Fehlern, oder bei Hinweisen auf fehlende oder zu überarbeitende Informationen.

Die unterstützten Typen finden sich hier. Für eine deutsche Überschrift muss manuell ein Titel (eingeschlossen in "") angegeben werden. Sinnvoll sind Überschriften wie Wichtig, Tipp, Todo, Bitte beachten, Vorsicht, Beispiel usw.

Verwenden von Tabs, Fußnoten usw.

Wenn es für die Lesbarkeit und Struktur von Vorteil ist, können und sollen auch Fußnoten, Tabs und dergleichen verwendet werden.

Rechtschreibung

Es wird die neue deutsche Rechtschreibung verwendet. Weiterhin:

  • „Neo“ (ist klar); Versionsbezeichnung bei Bedarf nur „2“, kein 2.0 – am besten weglassen. Andere Layouts können „Neo-basiert“ sein.
  • „Qwertz“
  • „Gnome“ (entsprechend den Namenskonventionen bei Wikipedia)
  • Die Andredepronomen du/dein/dir etc. werden kleingeschrieben.
  • Auf den „Einſatz“ des langen ſ soll komplett verzichtet werden.