Dokumentation erstellen

Diese Seite wird momentan erstellt und ist aktuell unvollständig


Hier ein paar Tipps und Tricks für eine gute Dokumentation. Diese Seite basiert grösstenteils auf einem Workshop vom FRUKDuK im HS 22, bei dem das Thema diskutiert wurde.

TL;DR

Strukturiere dein Wiki in Übersichtsseiten und allgemein gültige Anleitungen

Aktualisiere das Wiki ständig, auch für kleine Updates
Verwende Makros und Formatierung, damit Seiten lesbar und ansprechend sind
Falls es für deine Organisation relevant ist, übersetze das Wiki auch auf Englisch
Sortiere deinen Drive nach Ressort → Thema → Zeit
Solange der Drive gut sortiert ist, lege dort lieber zu viel ab, als zu wenig!

Wiki vs. Drive

Im Allgemeinen gilt:

Im Drive sind Dokumente/Informationen zu einem spezifischen Jahr bzw. Semester besser aufgehoben, da dort Dateiordner besser organisierbar sind. Ausserdem können Dokumente dort einfach und schneller für mehrere Personen (auch solche ausserhalb des Vorstands) zugänglich gemacht werden.

Ein Wiki wird am besten über längere Zeit immer weiter bearbeitet und ergänzt, da allgemeingültige Seiten auch sehr gut untereinander verlinkt werden können.



Beispiele:

Wiki

Drive
Ständig ergänzt über mehrere Vorstandsgenerationen
(z.B. Personen-, Sponsoren, Logindatenverzeichnis)		Während begrenzter Zeit von vielen Personen (auch ausserhalb des Vorstands) editiert
(z.B. Helfendenlisten, Zeitpläne, ToDo-Listen für spezifische Events)

Wird nach Themen/Begriffen durchsucht
(z.B. Protokolle, Zusammenfassungen von Sitzungen)

Wird nach Datum sortiert
(z.B. Planungsdokumente, Rechnungen)

langfristig und allgemeingültig
(z.B. HowTos, getroffene Entscheide)

kurzfristig, aber möglicherweise nochmal nützlich
(z.B. Rechnungen, Bestellungen, Planungsdokumente)

Source of Truth

Die "Source of Truth" ist die Quelle für eine bestimmte Information, die vorschreibt, was richtig ist. Was dort steht, stimmt. Es ist also besonders wichtig, dass das eindeutig ist, und es keine widersprüchlichen Informationen gibt. Für ein Wiki heisst das, dass z.B. eine Anleitung nur an einem Ort stehen sollte, an den von woanders nur noch verlinkt wird. Ändert sich etwas, dann muss nur der allgemeine Artikel editiert werden, und es entstehen keine falschen Informationen. Dasselbe gilt auch für Drives und Ähnliches, es gilt also: wo immer möglich, verlinke, embedde und verweise. Kopiere nach Möglichkeit nie.

Wikistruktur

Um eine einzelne Source of Truth zu gewährleisten, sollte ein Wiki sowohl allgemeingültige Anleitungen (unten "Prozesse" genannt) enthalten, als auch Anleitungen für bestimmte Events etc., die auf die Prozesse Bezug nehmen. Mithilfe von Embed-Makros und Tags können Seiten oft automatisch ergänzt werden, was viel Zeit und Verwirrung spart.


Einige sinnvolle Ideen für Übersichtsseiten für das Wiki der eigenen Organisation:

PersonenübersichtPersonen am Departement, im Verein (gut für Nachfolgende)
Login-DatenDaten für Konten bei Onlineshops etc.
SemestertimelineAuflistung aller ToDos, die jedes Jahr/Semester gleich sind
SponsorenlisteKontaktdaten möglicher Sponsoren für Events etc.
ToDo-Liste für grössere/generische EventsÜber Jahre gleich bleibende ToDos (z.B. für ESWE o.Ä.)

Protokollarchiv

Einen Spezialfall bilden Protokolle, da ins Confluence-Wiki eingefügte pdf-Dateien per Volltextsuche durchsuchbar sind. Will man also herausfinden, ob ein spezifisches Thema bereits diskutiert wurde, muss man nicht alle Protokolle einzeln durchgehen. Das geht zwar im Drive auch, aber mit weniger Optionen zum Filtern. 

Wiki updaten

Eine Wikiseite sollte zu jedem Zeitpunkt so aktuell wie möglich gehalten werden. Dazu ist es wichtig, laufend auch kleinste Updates durchzuführen, auch einzelne Sätze, Korrekturen, oder Aktualisierungen.

Makros

Wahre Poweruser:innen verwenden Makros gezielt (und nicht nur als Gimmick) um Seiten ansprechender und leichter navigierbar zu machen.

Spiele am Besten mal ein bisschen mit ein paar Sachen herum und finde heraus, was du nützlich findest.


Hier kann ein Mail-Template, eine genauere Anleitung oder eine Liste stehen, zum Beispiel auch in einem

stylischen Panel mit custom Format

Datei-/ Drivestruktur

Damit Dateien in einem Drive oder anderem Filesystem möglichst gut auffindbar sind, ist folgende Struktur zu empfehlen:

So sind auch Dateien, von denen man noch nicht weiss, wo sie sind, meist einfach zu finden. Hier noch einige weitere Tipps:

  • Thema möglichst eng fassen, lieber mehr Ordner haben, als Files ablegen, wo es nicht so ganz Sinn macht
  • Keine "Random" Ordner. Dort geht nur Zeug verloren.
  • In einem gut strukturierten Drive lieber zu viel ablegen, als zu wenig. Dein Nachwuchs wird es dir danken!