# Wikis erstellen
Wikis werden, genau so wie Issues etc. in Markdown geschrieben.
Was in Markdown möglich ist, ist im nächsten Thema beschrieben.
# Wikis erstellen: Screencasts von Mathis
Hier sind von Mathis aufgenommene Screencasts, die die Wiki-Nutzung (Einträge hinzufügen) sowie das Löschen fehlerhafter Links erklären:
# ⚠️ Änderungen / Neuerungen im GitLab Wiki werden immer in der Nacht auf das gehostete Wiki wiki.augenoptikerjobs.de (opens new window) übertragen!
# Inhaltliche Tipps
- weniger ist erstmal mehr (nach dem agilen Motto first make it work, then make it perfect) - 3 Sätze sind immer besser als nichts
- nutzt Markup, wie fett, kursiv oder
Tagsum wichtige Dinge hervorzuheben - nutzt auch gerne Emojis, für Hinweise: ⚠️ => Achtung, Warnung, Beachte, 💡/ℹ️ Hinweis, Bedenke, Takeaway, ❌ Vermeiden, Schlecht, Nicht machen
# 💡 Wenn ihr Emojis als Überschriften nutzt, werden die auch größer/auffälliger
# Formatierungs- und Ordnungsregeln
- Jedes Wiki soll mit den einzelnen Seiten (Themen) sinnvoll durchnummeriert werden.
- Die Nummerierung soll maximal dreistellig sein (also z.B. 3.2.1).
- Die erste Seite (0.) soll dabei immer das Inhaltsverzeichnis sein.
- Einrücken der Aufzählungen geht über 2 Leerzeichen am vorherigen Stichpunkt und 4 Leerzeichen vor dem nächsten.
- So wie hier
- Einrücken einer nummerierten Aufzählung geht nur einmal, deshalb soll beim 2. mal ein
*davor gesetzt werdenBeispiel
- Oberthema
1.1 Unterhemd von Oberthema- 1.1.1 Unterthema vom Unterthema
- Es sollen immer (sofern vorhanden) die weiteren Verlinkungen am ende der Wiki Seite geben
weiterführende Links
wenn von Ebene 1 (1. Infos zu Placing-You) auf Eben 2 (1.1 Onboarding) verlinkt wird, muss der komplette Pfad in der Verlinkung angegeben werden
Ebene 1/Ebene 2==>1.-Infos-zu-Placing-You/1.1-onboardingwenn von Ebene 2 (1.1 Onboarding) auf Ebene 3 (Erster Arbeitstag) verlinkt wird, muss nur das neue Thema angegeben werden (weil es die 3. Ebene bei GitLab quasi nicht gibt)
Ebene 3==>1.1.1-erster-Arbeitstagübergeordntenes Thema
wenn von Ebene 2 (1.1 Onboarding) auf Ebene 1 (1. Infos zu Placing-You) verlinkt wird, muss der ein Slash (../) in der Verlinkung angegeben werden (der Slash bedeutet, mein schiebt das Thema eine Ebene zurück (höher)) (siehe Bild)
/
Ebene 1==>/1.-Infos-zu-Placing-Youwenn von Ebene 3 (Erster Arbeitstag) auf Ebene 2 (1.1 Onboarding) verlinkt wird, muss nur das neue Thema angegeben werden (weil es die 3. Ebene bei GitLab quasi nicht gibt)
Ebene 2==>1.1-Onboarding
⚠️ Seit kurzer Zeit gibt es die Option Seitenpfad aus Titel generieren. Diese muss aktiviert sein, damit man die Seiten in die nächste Ebene einrücken kann (z.B. 1.-Infos-zu-Placing-You/1.1-onboarding):
==> Bitte überprüft immer die Verlinkungen innerhalb der Wiki-Seiten
# Fehler bei Verlinkungen im Wiki
⚠️ wichtig: Innerhalb von GitLab müssen die Groß- und Kleinschreibung bei den Verlinkungen nicht beachtet werden, innerhalb unseres Wikis (VuePress) ist es jedoch wichtig. Wenn hier eine Verlinkung (opens new window) als fehlerhaft angezeigt wird, überprüfe die genaue Schreibweise des Links.
⚠️ wichtig: In den Titeln/Verlinkungen dürfen keine Sonderzeichen verwendet werden (also kein (, (, -, _, [, ], #, |, ö, ä, ü, ...).
Kaputte Links sind auch hier aufgelistet: https://wiki.augenoptikerjobs.de/wikis/#wiki-seiten-mit-fehlerhaften-verlinkungen (opens new window)
# weitere Richtlinien
- Alle Seiten sollen untereinander verlinkt sein (siehe Organisation Wiki (opens new window)).
- Wenn ein neues Unterthema beginnt soll dies am Ende des Beitrags mit weiterführenden Links verlinkt werden.
- jedes Unterthema soll am ende des Posts das Oberthema verlinkt haben (übergeordnetes Thema).
- Sinnvolles Markup (fett, kursiv,
durchgestrichen...) nutzen und gerne viele Verlinkungen (als Erklärung). - Sinnvolle Strukturen am besten am Anfang überlegen (sonst ist es nachher mehr Arbeit die ganzen Links anzupassen).
- Wenn man neue Seite verlinkt und diese existieren nicht, werden diese durch das anklicken des Links erstellt.
- Wenn Unterthemen erstellt werden, muss es das Oberthema als Slug vor den Titel gesetzt bekommen.
- beginnt lieber im kleinen Rahmen (erweitern kann man später immer noch) => allg. Struktur ist wichtiger als ein hoher Detailgrad
- Beginnt eure Seite am besten mit einer Überschrift der ersten oder zweiten Ordnung (
# Überschrift, bzw.## Überschrift), denn diese werden auch in der Seitenleiste als Unterthema aufgelistet
Bsp:
- ⚠️ Nur Überschriften der Ordnung 1-3 (also
# erste Ordnung,## zweite Ordnung,### dritte Ordnung) werden in die Suche des Wikis einbezogen und sind damit essentiell:
# Probleme die entstehen können
- Bei Sonderzeichen (oder Emojis, etc.) in den Überschriften kann es zu Problemen mit Verlinkungen kommen (
/sollte sowieso vermieden werden, weil der Slash zum Einrücken für die verschiedene Ebenen genutzt wird) - Cashing Problem: wenn ihr eine Seite bearbeitet und etwas ändert, das bearbeitet aber nicht speichert (z.B. Browser/Tab schließt), kann es passieren, dass die Änderung dennoch von Gitlab in eurem Browsercache gespeichert!
- wenn ihr die Seite dann erneut bearbeiten wollt, kann es sein, dass der Browser dann eure gecachte (schon angepasste Version) nimmt und euch ausspielt (und nicht die angezeigt Version nimmt, die eigentlich im Wiki aktuell ist)
- falls dies passiert gibt es zwei Möglichkeiten das Problem zu lösen (wenn ihr von der angezeigten Version aus starten wollt):
- den Browsercache/Cookies von eurem aktuellen Fenster löschen/zurücksetzen (ihr werden wahrscheinlich bei allen Diensten ausgeloggt) -
mit Vorsicht zu genießen - mit einem frischen Browserfenster (am besten anonymes/incognito Fenster) starten, dann in GitLab die entsprechende Wiki-Seite aufrufen und bearbeiten. Nun solltet ihr die korrekte Version der Seite sehen. Den Inhalt der Seite kopieren (aus dem Bearbeitungsmodus heraus) und in den Editor des normalen Browser der entsprechenden Seite einfügen (wo es falsch angezeigt wurde) und speichern. Nun sollte es wieder überein stimmen.