# Beitragen

## Treiber-Entwicklung

Die Neo2-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 OS-Versionen her. Wenn du mitmachen möchtest oder dich für die Entwicklung interessierst, gibt es eine [Überblick-Seite](/Entwicklung/Ueberblick) mit weiteren Infos.

Wir nutzen [Gitea](https://git.neo-layout.org) zur Code-Verwaltung. Das Repository auf Github ist lediglich ein Mirror. Ist ein Github-Account vorhanden, kann man sich darüber auch bei unserem Gitea anmelden.

## Bugreports, Fragen, Vorschläge

Wenn Neo nicht so will wie erwartet oder es Fragen / Vorschläge gibt, kannst Du ein Issue im Gitea anlegen. Oder du meldest dich auf einem der [anderen Wege](/Kontakt/community) 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. Sende uns (neo) anschließend einen Pull Request.

### Syntax

Diese Dokumentation wird mittels [MkDocs](https://www.mkdocs.org) erstellt. Eine kurze Übersicht, wie man eigene Seiten definiert und füllt, findet sich [hier](https://www.mkdocs.org/user-guide/writing-your-docs/).

MkDocs verwendet [Github Flavored Markdown](https://guides.github.com/features/mastering-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:

  - [Fußnoten](https://squidfunk.github.io/mkdocs-material/reference/footnotes/)
  - [Admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) (auch [einklappbar](https://facelessuser.github.io/pymdown-extensions/extensions/details/))
  - [Verschachtelte Blöcke](https://facelessuser.github.io/pymdown-extensions/extensions/superfences/)
  - [Tabs](https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/)

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.


### Links und Image-Links

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

Interne Links zu anderen Markdown-Seiten oder sonstigen Dateien können sowohl relativ wie auch absolut angegeben werden. Beide Varianten sind sinnvoll:

  - Relative Links werden verwendet, wenn Seiten und Dateien referenziert werden, die stets relativ zur aktuellen Seite stehen. Auf diese Weise bleiben die Links erhalten, selbst wenn eine gesamte Kategorie verschoben/umbenannt wird.  
    
    ??? 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 (hier ist ein absoluter Link besser geeignet)

  - Absolute Links werden verwendet, um Seiten und Dateien zu referenzieren, die an ganz anderen Stellen liegen als die aktuelle Seite. Hierbei bleibt ein Link bestehen, selbst wenn die aktuelle Seite verschoben wird (jedoch nicht, wenn die referenzierte Seite ihren Platz ändert).  
  Im Unterschied zu relativen Links wird eine Markdown-Seite als Verzeichnis referenziert (d.h. ohne `.md` am Ende). Bei relativen Links **muss** dagegen `.md` angehängt werden.

    ??? example "Beispiele"
        - `(/Hardware/Truly)` verweist auf die Seite in der Datei `/Hardware/Truly.md`
        - `(/Benutzerhandbuch/images/kbdneo.png)` verweist auf die entsprechende Bilddatei

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, bspw. `(#manuelle-installation)` für die Überschrift _Manuelle Installation_. Wie man sieht, funktionieren Ankerlinks sogar 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.

#### Setzen von Links

  - 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](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types). 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.
