Das smarte Wiki, das beim Code lebt

---

---

EcoSystem Toolbox Teil 1: Smeagol

In der Softwareentwicklung ist es wichtig Informationen jeder Art zu teilen; egal ob es sich technische oder funktionale Details, Anforderungen oder Implementierungsdetails handelt. Ein gutes Wissensmanagement hilft dabei sich auf seine Arbeit zu konzentrieren und Fehler zu verhindern. Wahrscheinlich kennen Sie das aus eigener Erfahrung: Es ist einfach damit anzufangen Dinge zu dokumentieren, aber schwierig sie auch konsistent, an einem festen Ort und aktuell zu halten. Sobald ein Projekt für eine gewisse Zeit läuft, verbringt man des Öfteren viel Zeit damit ein bestimmtes Dokument zu suchen, oder ein neues zu erstellen um dann später festzustellen, dass es schon vorher existierte.

Warum Smeagol so hilfreich ist

Smeagol ist ein Wiki, das die Informationen in Git Repositories speichert und das mehrere Möglichkeiten bietet die Inhalte zu bearbeiten. Dadurch hilft es dabei die erwähnten Herausforderungen anzugehen:

• Informationen, die in allerlei unterschiedlichen Dateiformaten vorliegen können, können im Wiki zumindest verlinkt werden, so dass immer die aktuellste Version von Dokumenten gefunden wird. Dadurch kann das Wiki zu einem SPOC (SinglePointOfContact) für alle Informationen werden.
• Die Inhalte des Wiki önnen entweder durch die Weboberfläche von Smeagol, oder direkt übder die IDE der Entwickler bearbeitet werden. Dadurch ist es einfach für jederman nutzbar und es gibt keine Ausrede Informationen nicht zu aktualisieren.
• Da das Wiki teil des Git Repositories von Entwicklungsprojekten ist, können Informationen zu entsprechenden Branches gespeichert werden. Dadurch sind die Informationen Teil des Git Workflows und damit auch direkt mit dem Code verknüpft. Es ist also einfach herauszufinden welche Informationen zu Entscheidungen in der Entwicklung geführt haben.

So wird Smeagol benutzt

Hinweis: Da das Arbeiten mit dem Wiki via IDE so ziemlich das gleiche ist wie Code zu ändern, werden wir in diesem Post die Weboberfläche von Smeagol vorstellen.

Aktivierung des Wikis

Die Benutzung von Smeagol ist sehr einfach; man muss nur eine smeagol.yml Datei im Root- Verzeichnis eines Repositories ablegen um es zu aktivieren. Anschließend kann man das Wiki für dieses Repository über den Browser aufrufen. Smeagol kann entweder direkt über die URL (https://your EcoSystem/smeagol/) oder über das Warp Menü vom EcoSystem aufgerufen werden.

Dort werden alle Repositories angzeigt, für die man in SCM-Manager Berechtigungen hat. Es werden nicht nur die angezeigt, für die Smeagol schon aktiviert ist.

Erstellen der ersten Seite

Nun kann man das Repository auswählen, für das man Informationen in das Wiki eintragen möchte. Nachdem man einen Branch ausgewählt hat wird der Editor zum Bearbeiten der Startsite des Wiki angezeigt.

Hinweis: Wenn Smeagol für ein Repository noch nicht „aktiviert“ wurde, wird nach der Auswahl des Branches eine Fehlermeldung angezeigt.

Jetzt kann man schon damit anfangen die Dokumentation zu schreiben. Dazu kann man zwischen mehreren Spachen auswählen, unter Anderem Markdown. Nachdem das erledigt ist kann die Seite im Repository angelegt werden. Dazu muss man nur auf den „Speichern“ Button klicken. Anschließend pushed Smeagol die Änderungen automatisch an das Repository.

Für jede im Wiki angelegte Seite wird in dem Repository eine .md Datei angelegt. Wenn man Bilder benutzen möchte, muss man diese lediglich im Repository hinzufügen und anschließend im Wiki verlinken.

Seiten bearbeiten

Nachdem die erste Seite im Wiki erstellt wurde, werden für die Bearbeitung der Inhalte mehr Optionen auf der Seite angeboten. Zum Beispiel „Neu“ zum Anlegen von neuen Seiten, „Umbenennen“ oder „Bearbeiten“.

Wenn ein Wiki wächst, kann es schwierig werden den Überblick zu behalten was, wo aufgeschrieben wurde. Glücklicherweise organisiert Smeagol die angelegten Seiten in einer Baumstruktur, die man sich unter „Dateien“ anschauen kann.

Die Bearbeitung von Seiten erfolgt über den in Smeagol eingebauten Live-Editor.

Hinweis: Die Live-Preview funktioniert nur für Markdown und RDoc.

Neben den genannten Funktionen bietet Smeagol außerdem eine „Versionsübersicht“ und die „Letzte Änderungen“, über die man einsehen kann wie sich die Seite mit der Zeit verändert hat. Während die „Versionsübersicht“ die Commit-Historie für die Seite zeigt, werden unter „Letzte Änderungen“ alle Änderungen des gesamten Repositories angezeigt.

Zusammenfassung

Smeagol ist eine einfache, aber mächtige Erweiterung der Anwendungen des EcoSystem, denn es unterstützt durch seine einfache Handhabung dabei die Dokumentation zu einem Projekt aktuell zu halten. Das ist ein sehr wichtiger Faktor, da verteilt abgelegte und veraltete Dokumentation oft eine Ursache für Fehler und falsche Kommunikation ist. Daher hilf Smeagol dabei die Qualität und Effizienz in Projekten zu verbessern, indem es eine einfache Möglichkeit bietet Dokumentation zu erstellen und zu bearbeiten.

---

---