Online-Dokus mit einfachen Mitteln erstellen

Kann es im eher privaten Umfeld nützlich sein, Online-Dokumentationen zu erstellen? Hier mal einige Praxisfelder, an die man in diesem Zusammenhang vielleicht nicht sofort denkt:

• Hausverwaltung: Wartungslisten, Versicherungsinfos, Notfallpläne, Winterdienst, Heizungsangelegenheiten, Kontaktadressen, Smarthome-Regler
• Vereine: Mitgliedschaften, Checklisten für Veranstaltungen, Kontakte von Gruppenleitern, Abrechnungsverfahren für Auslagen, Einführungshinweise für neue Team-Kollegen
• Elterninfos: Terminübersichten, Ablaufhinweise Klassenfahrten, häufige Fragen, Einwilligungen, Sprechstunden
• Veranstaltungsplanung: Zuständigkeiten, Genehmigungen, Bestandslisten, Beschreibung von Räumlichkeiten
• Kleine Anleitungen: Flusensieb Waschmaschine, Entlüftung Heizung, digitalisierte Dokumente finden, Medienserver bedienen

Man sieht an diesen wenigen Beispielen, wie wertvoll eine „Mini-Wissensbank“ im Alltag sein kann. Für Handbücher und Anleitungen im technischen Bereich ist das Prinzip einer strukturierten Online-Doku schon lange gängig. Aber die Tools zur Umsetzung haben oft eine größere Lernkurve oder erfordern einen gewissen Pflegeaufwand für Aktualisierungen der Inhalte. Wir werden hier zur Umsetzung ein sehr einfaches Blog-System verwenden, das keine Datenbank benötigt und auf jedem günstigen Webspace läuft. Doch zunächst: Wie sieht das fertige System denn aus?

Die Komponenten des Doku-Systems

Startseite

Die Hauptkapitel der Dokumentation werden zusammen mit einer kurzen Beschreibung auf einer Übersichtsseite dargestellt. Die Titel sind Links, man kann also direkt in einen Bereich springen, für den man sich besonders interessiert. Den Hell-Dunkel-Modus kann der Leser mit einem Klick umstellen.

Aufbau und Struktur

Hinter der Übersichtsseite werden die Informationen strukturiert dargestellt:

Die Sidebar (1) zeigt Kapitel und Unterkapitel. In der Mitte befindet sich der eigentliche Inhalt eines Abschnitts (2). Ist dieser umfangreicher und weist verschiedene Überschriftsebenen auf, so erhält man in der rechten Spalte ein kleines Inhaltsverzeichnis mit anklickbaren Menüpunkten (3).

Navigation

Die eigentliche Navigation ist in der Sidebar zu finden. Zusätzlich gibt es im mittleren Bereich ein Breadcrumb-Menü oben (4) und „vorher/nachher“-Verweise unten (5).

Öffnet man einen Hauptabschnitt, so werden die dazugehörigen Unterabschnitte samt Erläuterungen angezeigt:

Damit erhält man auch bei einer großen Anzahl von Informationen eine saubere Ansicht. Es wird immer nur das eingeblendet, was gerade interessiert.

Inhalte

Texte, Fotos, Tabellen, Links, Videos – all das kann recht bequem über einen kleinen Editor eingefügt werden. Wer Markdown beherrscht, kann auch diese Auszeichnungssprache verwenden.

Das Ziel ist eine handbuchähnliche Darstellung, wie sie für Dokumentationen üblich ist. Komplexe Formatierungen oder Designeinstellungen darf man daher nicht erwarten.

Der Aufbau des Doku-Systems ist einfach gehalten, erfüllt aber in vielen Fällen seinen Zweck. Nun zur Frage, wie man das System installiert, mit Inhalten befüllt und aktualisiert.

Grundlage: Das Blog-System HTMLy

Über das „Brot-und-Butter-Blog-System“ HTMLy habe ich vor einiger Zeit einen ausführlichen Artikel geschrieben. Es genügt für unseren Zweck, wenn man weiß, dass es mit nur einer einzigen Datei auf jedem günstigen Webserver innerhalb einer Minute installierbar ist. Das System benötigt keine Datenbank, wird gut gepflegt und ist ausgesprochen flott unterwegs. Und: Es bringt die Funktion für die Erstellung von Dokus bereits mit. Es muss also nichts zusätzlich installiert werden. Man wählt lediglich das Theme „doks“ aus.

Nun noch von der Blog-Ansicht auf die statische Ansicht umstellen. Die Dokumentation besteht ja nicht aus chronologischen Einzelbeiträgen, die Inhalte werden vielmehr in Form „fixierter Webseiten“ abgelegt:

So, damit sind die „Vorarbeiten“ bereits abgeschlossen.

Anlegen der Struktur

Statische Seiten werden mit einem Klick auf den Menüpunkt in der Sidebar angelegt. Jede neue Seite bildet eine Hauptrubrik und kann beliebig viele Unterseiten aufnehmen. Es gibt keine tiefe Verschachtlung: eine Hauptebne plus eine Unterebene. Aber wie eingangs beschrieben: Längere Seiteninhalte können ein eigenes Inhaltsverzeichnis aufnehmen.

Die Darstellung der angelegten Seiten im Backend ist sehr übersichtlich. Für alle Funktionen gibt es verständliche Buttons. Das hat HTMLy sogar besser gelöst als viele seiner „großen Brüder“. Ein Verschieben von Seiten und Unterseiten kann per Drag-and-drop durchgeführt werden:

Aufnahme von Content

Das Einfügen von Texten, Verweisen, Grafiken usw. geschieht über einen kleinen Editor. Was alles möglich ist, aber ich in meinem HTMLy-Artikel bereits ausführlich beschrieben. Alles ist sehr einfach gehalten – neue Inhalte können rasch und unkompliziert eingegeben werden.

Pluspunkt „Aktualisierung von Inhalten“

Der Wert eines Dokumentationssystems steht und fällt mit der Frage, ob es leicht zu aktualisieren ist. Denn das ganze System nützt nichts, wenn ein Haupt-Zuständiger keine Zeit hat oder nicht greifbar ist. An diesem Punkt scheitern viele ähnliche Anwendungen, denn Änderungen lassen sich schlecht delegieren, wenn jemand nicht mit den technischen Feinheiten vertraut ist.

Bei unserem System ist die Pflege aber außerordentlich einfach: Einfach einen weiteren Account vergeben. Der Empfänger muss – fast – nichts vom System verstehen und sich auch nicht zur Struktur hangeln. Denn bei allen Seiten gibt es einen Edit-Button, so dass derjenige nur die Webseite aufschlagen muss und sofort Änderungen vornehmen kann.

Soll also ein Datum geändert oder eine Anmeldeinfo ergänzt werden, so kann das sehr simpel und flott von jedem, der einen Account besitzt, erledigt werden.

Blog und Doku parallel führen

HTMLy ist ein – sehr gutes – Blog-System. Es bietet sich also an, diesen Bereich neben dem Doku-Bereich zu nutzen. Im Backend gibt es zwar keinen gesonderten Schalter dafür, aber die Entwickler haben diese Variante trotzdem integriert. Dazu muss man nur 1 Wort ändern: In der Datei ../config/config.ini den Eintrag „blog.enable“ auf „true“ setzen – also „blog.enable = true“. Erledigt. Der Blog-Bereich wird damit im Verzeichniszweig „/blog“ aufgebaut. Erreicht man beispielsweise die Doku mit „meine-doku.de“ so kann über einen Menüpunkt der dazugehörige Blog mit „meine-doku.de/blog“ aufgerufen werden.

Falls für den Blog ein völlig anderes Design gewünscht ist, so ist die einfachste Lösung eine Doppel-Installation in zwei Verzeichnissen. Eventuell möchte man einen bestehenden Blog oder eine existierende Webseite mit der Dokumentation ergänzen. HTMLy lässt sich überall installieren, ohne zu stören. Sogar in einen Unterpfad einer WordPress-Installation. Mit einem Link kann die Doku vom bestehenden Angebot aus aufgerufen werden. Da HTMLy auch die Gestaltung von Menüs übernimmt, definiert man in seinem Dokumentensystem dann einen „Zurück“-Link.