Das liebe Dokumentieren

Weil ich mich wieder etwas zwangsläufig mit dem Thema beschäftige – also immer wieder auf eigene Notizen bzw. Unterlagen zurückgreifen und vor allem diese Inhalte öfters verschiedenen Gegenübern zur Verfügung stellen muss – habe ich mich endlich an ein Dokumentations-Tool gewagt, um das ich schon seit Jahren immer einen Bogen gemacht hatte: Sphinx.

Sphinx

Wer schon einmal umfangreiche Texte verfasst hat, die nicht nur für Blogs, Emails oder dergleichen gedacht waren, sondern eher dem strukturierten Erstellen von Inhalten – also Dokumentationen – der greift ja in der Regel auf Word oder ein ähnliches Programm zurück und tippt halt dort so seine Zeilen munter oder müde vor sich hin. Beispielsweise Diplomarbeiten und all diese Dinge, die man inhaltlich und visuell irgendwie sinnvoll aufbauen muss, so dass sich Andere zurecht finden, aber man auch selber schlussendlich.

Wie, was, nun… mh.
Eine der größten Herausforderungen bei der Sache sind natürlich nicht nur die Inhalte (no na net), sondern auch die Art und Weise. Beispielsweise administriere ich bis heute immer noch da und dort diverse Webseiten und deren Tools im Backend, auch wenn ich das weiter und weiter einschränke. Dazu habe ich mir natürlich im Laufe der Zeit notwendigerweise eine kleine Sammlung von selbst entdeckten oder geformten Wege der Betreuung sowie Umsetzung, Code-Schnippseln und sonstige Anleitungen zusammengetragen und immer wieder schicke ich Teile davon dann entsprechend einem User bei Bedarf weiter.

Nun ist das Leben natürlich so, dass man immer wieder mal da und dort Inhalte ergänzt, dass da und dort Fragen auftauchen und einige Dinge sich im Laufe der Zeit auch ändern. Sagen wir mal, zum vereinfachten und verbesserten Verständnis, es handelt sich um sowas wie eine aktive, lebende Diplom-Arbeit mit einer Vielzahl an Informationen und Themengebiete, die sich immer wieder erweitern und auch neu erfasst und aktualisiert werden müssen.

Nun bietet sich für diesen Zweck natürlich wunderbar so ziemlich jede Wiki-Lösung an, die man so in der digitalen Welt da draußen findet… leicht auf dem eigenen Server oder auch USB-Stick zu installieren und was Wikipedia kann, kann man eben selber genauso – im kleinen Maßstab und in bunten Formen. Gibt es in vielen Firmen und sie sind auch meine erste Wahl, wenn mich jemand fragt, wie kann er oder sein Team sich besser strukturieren und eine Vielzahl an Infos zusammentragen und zugleich einfach Anderen zur Verfügung stellen…? Mit einem internen Wiki. So gesehen könnte ich hier den Eintrag auch beenden, denn es ist alles gesagt damit.

Die Suche
Ich wäre nicht ich, wenn ich mich nicht damit zufrieden geben würde und zudem auch innerlich getrieben dem Weg folge, der mir es zum Beispiel auch ermöglicht, die Inhalte nicht nur als Webseite, sondern auch strukturiert als PDF zu exportieren. Oder als Word-Dokument. Oder als Textdatei oder auch als Vorlage für einen Blog wie diesen hier und so weiter… wer mich ein bisschen kennt, weiß nun eh schon, um was es mir geht.

Richtig, die Suche nach dem Format, das mir alle Wege offen hält, ohne doppelte Arbeit vollrichten zu müssen. Denn ja, ich kann auch faul sein *starkesHustenandieserStelle* und je älter ich werde, umso mehr ödet mich die Vielfalt am Gerät vor meiner Nase an. Auch an den Lösungen generell. Ich will’s einfach und auf Knopfdruck quasi. Außerdem will ich unabhängig bleiben und all diese anderen psychologischen Hürden der eigenen Mentalität im Leben befriedigen.

Denn es gibt noch eine weitere Herausforderung… da ich die Notizen und Dokumentationen zu den ganzen Tools und Anwendungen nicht nur selber verwende, sondern auch Menschen, die sich nicht so tief in die Materie arbeiten wollen, ist eine Suchfunktion wichtig, ebenso eine Übersicht von Stichwörtern und auch eine generell leicht verständliche Struktur der Inhalte – das Stichwort „TOC“… Table of Contents – also ein Inhaltsverzeichnis, wie man es in fast allen Büchern findet, ebenso eine Übersicht von Abschnitten bei langen Texten.

Per Hand? Na sicher nicht.

Eine Möglichkeit: Sphinx
Na, raucht der Kopf schon? Schon mal in Word gemacht? Mühsam meistens, vor allem für Menschen wie mich, die Word & Co. nur als Notbehelf sehen und viele bunte Themen gemeinsam behandeln wollen. Und deswegen habe ich mich nun endlich in tiefer Nacht dem Tool Sphinx gewidmet, ein „Ding“, über das ich schon oft gestoßen bin, aber immer als zu „komplex“ empfunden hatte und als zu „technisch“. Das war allerdings eine ziemliche Fehleinschätzung meinerseits.

Gleich mal als Prinzip – ursprünglich ist Sphinx eher für die Dokumentation von Python-Projekten eingesetzt worden, also im Bereich der Programmierung. Dort gibt es viel Code, viele Fragen und Tonnen an Erklärungen und Hinweisen. Und nachdem niemand – auch Geeks und Nerds – damit von Natur aus geboren werden, muss man sich ja irgendwie dieses Wissen aneignen können… und das passiert mithilfe der Dokumentation, FAQs (Frequently asked questions) und Tutorials. Und wenn mal eine Sprache oder Code ein paar tausend Kürzel, Befehle und Co. beinhaltet, dann reicht ein einfaches Word-Dokument nicht mehr so ganz aus bzw. wird es schnell schwierig – abgesehen davon, dass viel „Code“ auch als solches angeführt werden und natürlich „artgerecht“ dargestellt werden muss.

Lohnt sich da der Blick auf Sphinx? Wer mich noch ein wenig mehr kennt, der weiß auch, dass ich aus einem alten Tisch und einem Lattenrost ein Sofa mache – nicht weil ich es kann, denn das kann jeder Depp, sondern ganz einfach weil es funktioniert, einfach ist und nicht viel Aufwand und kaum Kosten erfordert. Das Grundprinzip.

Natürlich – es gibt zum Beispiel für technische Dokumentationen, als auch Schul-, Diplom-, Doktorarbeiten und dergleichen eigene Tools, Programme oder Erweiterungen, die einem helfen und bei der Umsetzung unterstützen – aber ich habe noch eine weitere Vorgabe… ich will quasi mit reinen Textdateien arbeiten.

rST Texte

Purer Text – sehr fein.
Und in Sphinx arbeitet man mit dem rST-Format, dem reStructuredText-Format. Keine Angst, klingt schwerfällig, kann man aber mit jedem beliebigen Texteditor schreiben… denn es ist eigentlich eher die Art und Weise, wie man den Text verfasst. Anstatt wie in Word ein Wort zu markieren und dann via Button den Text fett zu machen und nicht genau zu wissen, woher das Fett eigentlich herkommt und wo sich das da in dem Dokument irgendwie irgendwo versteckt und wie überhaupt eingebaut ist, schreibt man das in rST sozusagen selber.

Das ist eine Überschrift
====================
Das ist ein *kursives Wort* und das hier ein **fettes Wort**.

…und so weiter. Wirkt hier optisch etwas sperrig, aber hier ist ein schönes Beispiel, wie das dann in großem Format ausschaut. Man sieht… schlichter, einfacher Text. Wer ein bisschen mehr Materie intus hat, würde natürlich das einfachere, ebenso allseits bekannte MarkDown ins Spiel bringen, aber nachdem Sphinx nicht nur rST verwendet, sondern auch noch mehr an anderen Optionen ermöglicht, kann man damit gut leben.

Wie läuft das also ab?
Man schreibt seine Dokumentationen, Tutorials und sonstige Texte einfach im rST-Format und speichert sie einfach als Textdateien ab… also zum Beispiel WordPress.rst, Galerie.rst, Emails.rst, Windows.rst, Anleitung.rst, Hunde-Barfen.rst, Kaninchen-Gymnastik.rst und so weiter. Und es gibt zum Beispiel eine Index.txt-Datei, in der man eine nette Willkommen-Seite schreibt, ein bisschen Hallo-Blabla und eine Übersicht (bzw. Links zu) über die Hauptthemen.

Die Features
Mit einem einfachen Funktionsaufruf in der Konsole alias make Html generiert Sphinx aus all diesen Dateien (und Ordnern, Fotos,…) eine komplette Webseite – nicht nur mit den Texten, sondern auch mit einer Suchfunktion, die gesuchte Wörter visuell dann hervorhebt, erstellt aus den Seiten ein Stichwortverzeichnis, ermöglicht ein Durchblättern durch die Artikel und zudem erstellt Sphinx aus den Überschriften auf einer Seite eine kleine Seitennavigation – ich kann also gleich direkt zu einer der Überschriften bzw. Themenpunkt auf einer Seite weiter unten springen… sprich Sprungmarken.

Sphinx

Oben die Online-Version, darunter ein einfacher PDF-Export.

PDF-Export

Eine sehr feine Sache also… noch dazu gibt es vorgefertigte Layouts, die auch auf Smartphones gut dargestellt werden und optisch ansprechend sind – auch so eine Schwierigkeit bei vielen, langen und umständlichen Inhalten.

Noch ein Bonus?
Abgesehen von dem vorherigen Punkt bietet das rST-Format auch die Möglichkeit, schnell und unkompliziert aus den Inhalten PDFs zu erstellen (inklusive der Formatierung, Inhaltsverzeichnis und Co.) als eben auch die Freiheit, die Texte in andere Tools, Programme oder Webseiten (mit ein paar Anpassungen) zu importieren. Sagen wir ganz vorsichtig, es ist eine Art der universalen Schreibweise und Format.

Sphinx läuft auf Linux, Windows und Mac OSx und ist leicht zu installieren, erfordert aber natürlich dann schon so ca. eine halbe oder ganze Stunde Einarbeitungszeit, bis man das erste sinnvolle Ergebnis hat und ein Gefühl bekommt, was für ein Tool man da eigentlich verwendet. Hat man diesen Schritt aber überwunden, es sich eingerichtet und angepasst, dann ist es wie Schokolade essen… einfach machen und nicht mehr viel darüber nachdenken.

Zukünftig schreibe ich also damit Anleitungen und Dokumentationen und kann sie damit leicht dem Gegenüber dann online oder in einem anderen Format – je nach Bedarf – zur Verfügung stellen. Und recht gut archivieren. Fein.

UPDATE
Ich habe eine kleine Demo online gestellt, um zu zeigen, wie sowas ausschauen kann. Die Links zum Durchblättern habe ich allerdings deaktiviert. Der Menüpunkt Abschnitte zeigt immer die jeweiligen Überschriften bzw. Sprungmarken der jeweiligen Seite an. Source zeigt Euch die originale Textdatei und Formatierung an, die Sphinx zu der Webseite formt.