Online-Dokumentationen und Web-Bücher erstellen

28.03.2017

Für Online-Dokumentationen und Web-Manuals hat sich eine quirlige Tech-Nische entwickelt, die auch für den Mainstream interessant werden könnte.

Wenn es um Web-Publising geht, denkt man vor allem in drei Kategorien:

  • Die Corporate Website mit einer hierarchischen Struktur und eher zeitlosen Infos.
  • Der Blog (oder die Newsseite bzw. das Magazin) mit zeitbezogenen Inhalten.
  • Das Wiki als eine lebendige Sammlung von Einzelartikeln.

Wer Texte im Web veröffentlichen will, greift also zu einem CMS, einer Blog-Software oder einem Wiki-System.

Wie sieht es aber mit anderen Text-Formen wie Bücher, Handbücher, Dokumentationen, Manuals, Whitepapers und ähnlichen abgeschlossenen Werken aus? Die meisten denken dabei sofort an PDFs oder allenfalls noch an ein eBook. Als Webseite führt das klassische Textwerk dagegen ein trauriges Nischen-Dasein.

Die quirlige Nische

In einem Bereich ist diese Nische allerdings gar nicht so traurig, sondern im Gegenteil ziemlich lebendig und quirlig: Im Bereich der User-Manuals für Software und der Code-Dokumentation.

Die Dokumentation von Grav Beispiel: Die sehr schöne Online-Dokumentation von GRAV CMS

Der technische Standard für User-Manuals und Dokumentationen war lange Zeit das von O’Reilly entwickelte und auf XML basierende DocBook. Daneben kamen häufig auch Wiki-Systeme wie Confluence in Verbindung mit Ticket-Systemen wie JIRA zum Einsatz. Für klassische Code- oder API-Dokumentationen werden dagegen meist Generatoren wie Doxygen, ApiGen, JavaDoc, JSDoc oder PHPDocumentor verwendet. Während bei DocBook und Wiki-Systemen die redaktionelle Arbeit im Vordergrund steht, werden mit Hilfe von Generatoren im Kern die Kommentare aus dem Quellcode extrahiert und daraus automatisierte Dokumentationen erstellt.

Das eher umständliche und redaktionsunfreundliche Format XML hat in den vergangenen Jahren viel Konkurrenz bekommen. Eine Alternative entstand beispielsweise im Jahr 2008 mit der Python-Software Sphinx. Sphinx ist dabei eine Mischung aus automatischem Code-Dokumentator und einem redaktionellen Editor. Bei dem redaktionellen Teil setzt Sphinx nicht auf XML oder einem Wiki, sondern auf eine Wiki-ähnliche Auszeichnungssprache mit dem Namen reStrucutredText. Mit dieser einfachen Markup-Sprache werden kleine Text-Dateien erstellt, die von Sphinx mit Hilfe eines Templates in einen Web-Auftritt verwandelt werden. Die Software dürfte bis heute eine der beliebtesten Tools für Dokumentationen sein.

Ebenfalls im Jahr 2008 ist die Social Coding Plattform GitHub erschienen, und mit ihr der zu GitHub gehörende statische Website-Generator Jekyll. Ähnlich wie bei Sphinx kann man auch mit Jekyll aus einfachen Text-Dateien statische HTML-Seiten erstellen. Anders als Sphinx nutzen Jekyll und andere statische Website-Generatoren wie Middleman oder Hugo die Auszeichnungssprache "Markdown". Kommentare aus Quellcode werden bei statischen Website-Generatoren nicht verwendet, die Generatoren werden also rein redaktionell eingesetzt.

Markdown

Wer noch nie etwas von Markdown gehört hat: Markdown ist eine sehr einfache Auszeichnungssprache, die dem Markup von Wikipedia ähnelt. Markdown-Dateien haben die Endung .md. Man kann sie mit jedem simplen Text-Editor erstellen. Für die Formatierung werden eingängige Sonderzeichen verwendet, eine Überschrift ersten Grades sieht beispielsweise so aus:

# Überschrift

Gefolgt von ganz normalem Fließtext.

Markdown wurde 2004 spezifiziert. Inzwischen gibt es diverse Variationen und Erweiterungen wie Markdown Extra, Commonmark und so weiter. Außerdem ist mit "API Blueprint" sogar eine Markdown-Syntax für die Beschreibung von APIs entwickelt worden.

Die Kombination aus Markdown, GitHub und statischen Website-Generatoren hat auch im Bereich der Online-Dokus und Web-Manuals einen enormen Aufschwung erlebt. Allerdings schwingt selbst bei diesen vergleichsweise einfachen Lösungen ein erheblicher Nerd-Faktor mit: Ohne eine innige Freundschaft zur Konsole und ohne rudimentäre Entwickler-Kenntnisse dürften die meisten Nutzer aufgeschmissen sein.

Bevor wir später in tiefere Nerd-Schichten vordringen, stelle ich erst einmal ein paar Tools vor, die auch von Nicht-Entwicklern für Handbücher, Dokus und ähnliche Publikationsformen genutzt werden können.

Content Management Systeme

Am naheliegendsten ist es natürlich, für Web-Bücher, Manuals und Dokus einfach klassische Content-Management-Systeme zu verwenden. Und natürlich kann man auch WordPress in diese Richtung verbiegen, wenn man denn unbedingt will. Allerdings sind klassische CMS wie WordPress, Typo3, Joomla! oder Drupal einfach gnadenlos überdimensioniert, wenn nicht komplett sinnfrei oder zumindest extrem zweckentfremdet. Denn schließlich geht es nur um ein paar speziell aufgebaute Text-Seiten mit einer Navi und nicht um einen komplexen und beliebig erweiterbaren Web-Auftritt mit ein paar Dutzend Features.

Ein guter Kompromiss sind Flat-File-Systeme, denn sie sind von der Komplexität her angemessen einfach, verbrauchen keine Datenbank-Ressourcen und nutzen in der Regel Markdown-Files für die Inhalte. So nähert man sich wenigstens in einem Punkt dem etablierten Standard im Technik-Umfeld an.

Unter den Flat-File-Systeme habe ich folgende Lösungen und Themes für Manuals, Bücher und Dokumentationen gefunden:

Theme CMS Kosten Beispiel und Bemerkungen
kdoc Kirby 0 + 79,- Kirby-Lizenz Sehr rudimentär
KirbyBook Kirby 19,- (Standard) / 29,- (Dev) + 79,- Kirby-Lizenz Ausgabe als E-Pub
Learn2 Grav 0,- Beispiel Grav-Doku
Docs Bludit 0,- Beispiel Bludit-Doku
Bits and Pieces Pico 0,- Recht rudimentär

Wer absolut nicht auf WordPress und andere komplexe CMS verzichten kann, findet beispielsweise bei wpmayor einen ersten Überblick. Aus meiner Sicht sind allerdings auch die meisten Themes komplett überdimensioniert und gehen an den Bedürfnissen der Nutzer vorbei.

Daux.io

Exakt zugeschnitten auf die Anforderungen von Dokus, Manuals oder Web-Bücher ist die PHP-Software Daux.io. Daux.io fehlt zwar eine Autorenoberfläche und ist damit kein klassisches CMS. Dennoch kann man Daux völlig ohne Code-Kenntnisse und ohne lästige Installations-Routinen nutzen. Einfach runterladen und auf den Server oder in die lokale Entwicklungsumgebung schieben, fertig. Das ganze ist technisch noch simpler, als einen eigenen WordPress-Blog einzurichten.

Die Inhalte werden mit einfachen Markdown-Files auf dem Laptop oder Computer erstellt. Anschließend organisiert man die Files in einer Ordner-Struktur und schiebt alles in den Docs-Folder von Daux (auf einem Live-Server per FTP). Die Software generiert dann ‘on the fly’ einen Web-Auftritt.

Der Dokumenten-Generator Daux.io

Bei Daux.io ist der dynamisch generierte Web-Auftritt nicht unbedingt als Endprodukt gedacht, sondern als Preview während des Schreib-Prozesses. Allerdings kann man auf das bisschen Ressourcen-Verbrauch auch pfeifen und einfach die Preview als Web-Auftritt hosten. Wenn man die Seite dagegen statifizieren will, muss man die Konsole bemühen und die statische HTML-Version mit einem kurzen Befehl erzeugen.

Die Standard-Themes von Daux.io sind eher für Code-Dokumentationen gedacht. Sofern man ein paar Entwickler-Kenntnisse hat, kann man allerdings auch eigene Themes erstellen.

DokumentUp und Flatdoc

Für sehr einfach gehaltene One-Page-Dokumentationen auf Markdown-Basis bieten sich zwei kleine JavaScript-Projekte an. Beide Projekte können (beinahe) ohne Code-Kenntnisse verwendet werden, zumindest wird jeder damit zurecht kommen, der ein wenig HTML-Quellcode lesen kann.

Name Sprache/System Beschreibung
Flatdoc JavaScript Dynamische HTML-Ansicht eines Markdown-Files
DocumentUp JavaScript Dynamische HTML-Ansicht eines Markdown-Files

Flatdoc ist ein simples HTML-Template mit ein paar eingebundenen JavaScript-Ressourcen. Im Quellcode des HTML-Templates muss man lediglich eine Markdown-Datei bzw. dessen Quelle angeben, und schon wird die Markdown-Datei in das Template "eingebunden" und als hübsche One-Page-Dokumentation angezeigt. Die Angabe im HTML-Quellcode sieht ungefähr so aus:

<script>
    Flatdoc.run({   
        fetcher: Flatdoc.file('Readme.md')
    });
</script>

Die Markdown-Datei kann genausogut auf irgend einem Server liegen, oder auf GitHub, wofür es ursprünglich wohl entwickelt wurde:

fetcher: Flatdoc.file('http://yoursite.com/Readme.md')
fetcher: Flatdoc.github('trendschau/tumbly')

DocumentUp macht im Prinzip das gleiche wie Flatdoc, allerdings ist DocumentUp ein gehosteter Service, der ganz auf GitHub ausgerichtet ist. Man kann einfach in die URL des Services seinen GitHub Nutzernamen und den Projektnamen eingeben. Die readme.md-Datei des Projekts wird dann in das Doku-Template eingelesen. Zum Beispiel: http://documentup.com/trendschau/tumbly. Man kann das Script auch zu seinem GitHub-Projekt hinfügen und so als selbstgehosteten Service verwenden.

Atlas von O’Reilly

GitHub hat nicht nur die Arbeit von Web-Entwicklern, Technikern und Nerds verändert, sondern auch Autoren und Publisher wie O’Reilly inspiriert. Und O’Reilly ist einmal mehr ein Verlag, der neue Techonologien für normale Autoren zugänglich gemacht hat. In diesem Fall mit dem Projekt Atlas.

Atlas von O'Reilly

Atlas wirkt erst einmal wie eine ganz normale CMS-Plattform ähnlich wie WordPress.com, nur eben speziell für Bücher und verwandte Publikationsformen. Sprich, man kann bei Atlas einen Account anlegen, dann über die Autorenoberfläche seine Bücher schreiben und sie am Ende als PDF, Mobi, EPUB oder HTML veröffentlichen.

Tatsächlich ist Atlas jedoch auf der Versionierungssoftware Git aufgebaut. Entsprechend lassen sich die Projekte auch per Git auf den lokalen Computer clonen, dort bearbeiten und dann wieder zurück in das Atlas-Projekt pushen. Genauso ist es möglich, sein Projekt mit seinem GitHub-Account zu synchronisieren oder gemeinsam mit anderen Nutzern zu bearbeiten. Als Formatierungssprachen akzeptiert Atlas Markdown und AsciiDoc.

Atlas ist für weniger technik-affine Autoren eine super Lösung, um sich behutsam Themen wie Git, GitHub, Markdown, APIs oder CLI (Command Line Interface) zu nähern. Denn man kann diese Technologien bei Atlas nutzen, muss es aber nicht. Außerdem lassen sich über Atlas wirklich professionelle Publikationen erstellen, da die Themen Buch-Satz, Layout und Typographie so professionell behandelt werden, wie man es von einem Verlag erwartet. Der einzige Nachteil ist, dass man Atlas nicht herunterladen und selbst installieren kann. Allerdings kann man sämtliche End-Formate herunterladen und beliebig nutzen, d.h. ein PDF an einen Drucker schicken oder die HTML-Version auf seinem eigenen Server hosten.

GitHub, Git Pages und Jekyll

Jetzt sind wir bei GitHub angekommen und damit schon tiefer in Nerd-Sphären vorgedrungen. Alle ab jetzt vorgestellten Lösungen erfordern eine Arbeit mit der Konsole und am besten auch ein paar Entwickler-Kenntnisse. Wer noch nie etwas von Git, GitHub, Git Pages, Jekyll oder anderen statischen Seiten-Generatoren gehört hat, bekommt ein paar Stichpunkte an die Hand:

  • Git ist eine freie Versionierungs-Software und heute Standard in der Entwicklung.
  • GitHub ist eine kommerziell betriebene Social-Coding-Plattform, die auf der Git-Software aufbaut.
  • Git Pages ist ein Service von GitHub zur einfachen Erstellung und zum Hosting statischer Webseiten.
  • Jekyll ist ein statischer Webseiten-Generator, der aus der Feder des GitHub-Gründers stammt. Er wird für Git Pages eingesetzt.
  • Statische Website-Generatoren wie Jekyll, Hugo oder Middleman sind Programme, mit denen man über die Konsole und (meist) auf Basis von Markdown-Files statische HTML-Auftritte erzeugen kann.

GitHub, GitPages und statische Website-Generatoren sind deshalb so en vogue, weil der Workflow für Entwickler sehr einfach ist und man die Dokumentationen oder Manuals direkt zusammen mit seinem Open Source Projekt hosten kann. Dadurch gibt man anderen Entwicklern auch gleich die Möglichkeit, Änderungen an der Doku per Git vorzuschlagen.

GitHub bietet zwar auch die Möglichkeit, das eingebaute Wiki-System zur Dokumentation seiner Projekte zu nutzen. Für längere Dokumentationen empfielt GitHub aber Git Pages und liefert gleich auch eine Anleitung für Dokumentationen auf Git Pages mit.

Das ganze funktioniert bis zu einem gewissen Punkt auch ohne Git, Jekyll und Konsolen-Arbeit. Man kann einfach über die Oberfläche von GitHub einen /docs Ordner in seinem Projekt anlegen und darin eine Markdown-Datei erzeugen:

GitHub: Dokumentenordner anlegen und Markdown-File erstellen

Anschließend kann man im Projekt unter Settings eine Quelle (Docs) für die Github Page angeben und ein Theme auswählen. Fertig ist die GitHub Page:

GitHub: GitHub Page aktivieren

Die Hürden für Nicht-Entwickler entstehen erst, wenn man ein passendes Theme verwenden will. Denn die wenigen für Git Pages vorinstallierten Themes sind für Dokumentationen eher ungeeignet. Stattdessen könnte man beispielsweise das Jekyll Documentation Theme verwenden. Das Theme kann man allerdings nicht wie bei WordPress einfach runterladen und dann per FTP irgendwo hinschieben. Sondern zum Hochladen des Themes und zur Generierung der Seite benötigt man eben Git und Jekyll:

  • Zuerst muss man Git bei sich lokal installieren, sich mit der Funktionsweise und den verschiedenen Befehlen vertraut machen. Windows-Nutzer verwenden in der Regel die Variante GitBash.
  • Da Jekyll eine Ruby-Software ist, muss man auf seinem lokalen PC oder Laptop eine Entwicklungsumgebung für Ruby einrichten.
  • Zusätzlich braucht man die Software Bundler, um Abhängigkeiten (Dependencies) zu managen (ähnlich wie Composer für PHP).

Abschließend wird das Theme und die Doku über einen Git-Befehl in das Repository auf GitHub gepushed und die Generierung der statischen Webseite über einen Jekyll-Befehl initiiert (hier nochmal alles auf YouTube erklärt). Alles klar soweit?

Für Entwickler ist das natürlich klar. Aber Nicht-Entwickler dürften eher Bahnhof verstehen. Aus diesem Grund glaube ich auch nicht, dass diese Technik in absehbarer Zeit von der Entwickler-Szene auf den Mainstream herüberschwappt. Für die breite Masse dürften die Einstiegs-Hürden einfach zu hoch sein.

Spezielle Generatoren und weitere Services

Jekyll, der von GitHub entwickelte und auf Git Pages eingesetzte statische Website-Generator, ist eher auf Blogs ausgelegt und für Handbücher oder Dokumentationen nur bedingt geeignet. Es gibt jedoch zahlreiche Alternativen, die sich auf diese Publikationsformen spezialisiert haben.

Name Sprache/System Beschreibung
Slate Ruby Generiert Doku aus Markdown-Files und deployed direkt auf GitHub Pages
Couscous PHP Generiert Doku aus Markdown-Files und deployed direkt auf GitHub Pages
Markdoc Python / Unix Generiert eine Art Wiki aus Markdown-Files.
MKDocs Python Generiert eine Doku aus Markdown-Files.
BookDown R, Pandoc, LaTeX (für PDF) Generiert HTML, LaTeX, EPUB, MOBI
readthedocs.io Unbekannt Gehosteter Service, der Dokus aus Repositories erstellt
GitBook Unbekannt Kommerzielle Lösung
readme.io Unbekannt Kommerzielle Lösung

Mit über 13.000 Sternchen scheint Slate das populärste Tools zu sein, um auf Basis von Markdown-Files eine (API-)Dokumentation zu erstellen. Slate wird von einer Vielzahl großer Brands genutzt und setzt technisch auf dem statischen Website-Generator Middleman auf. Wie üblich kann man die HTML-Doku über einen Konsolen-Befehl erstellen und dann auch auf Git Pages publizieren.

Das Projekt Couscous scheint dagegen als Alternativ-Projekt für PHP unterwegs zu sein. Auch bei Couscous kann man die Doku im Stil statischer Website-Generatoren einfach per Befehl generieren und dann auf Git Pages veröffentlichen. Die Projekte MKDocs und Markdocs sind dagegen statische Site-Generatoren für die Python-Welt, ebenfalls spezialisiert auf Dokus bzw. Wikis mit Markdown.

Wer die Doku nicht lokal mit einem statischen Site-Generator erstellen will, der ist bei dem Service ReadTheDocs gut aufgehoben. Die Plattform ReadTheDocs ist aus dem Sphinx-Projekt entstanden und hostet unzählige Online-Dokumentationen mit dem unterschiedlichsten Entstehungs-Hintergrund. ReadTheDocs unterstützt neben anderen Versionierungs-Plattformen auch Git und GitHub: Man kann sich einfach bei ReadTheDocs anmelden und das GitHub-Repository mit der Markdown-Doku angeben. Anschließend generiert ReadTheDocs eine Online-Doku, die dann auf der ReadTheDocs-Plattform gehostet wird.

Speziell auf Bücher ist das Open Source Projekt BookDown ausgerichtet. Allerdings kommt BookDown aus der Welt der R-Programmiersprache, die speziell für statistische Berechnungen und Grafiken entwickelt wurde. BookDown dürfte also nur für eine sehr spezielle und technisch orientierte Zielgruppe in Frage kommen.

Daneben gibt es natürlich ein Vielzahl an kommerziellen Diensten, die ein Publishing auf Basis von Git oder per GitHub anbieten. Beispiele sind GitBook und readme.io. Beide Angebote haben eine recht saftige Preisspanne und richten sich damit eher an Unternehmen. Allerdings tun sich beide Services auch etwas schwer, ihren USP gegenüber den oben genannten freien Lösungen zu vermitteln.

Letzter Tipp: Docco als schlanker Code Dokumentator

Anders als die prosa-orientierten Online-Manuals, Tutorials oder Web-Bücher sind Code-Dokumentatoren nur noch etwas für Software-Entwickler. Alle Code-Dokumentatoren funktionieren ähnlich: Sie extrahieren die Kommentare aus dem Quell-Code einer Software und generieren daraus technische Dokumentationen.

Es ist an dieser Stelle müßig, eine Liste aller Code-Dokumentatoren zu erstellen. Der Wikipedia-Artikel zu Code-Dokumentatoren listet bereits 50 auf und ist dennoch nicht vollständig. Entwickler dürften den für ihre Entwickler-Sprache führenden Code-Dokumentator ohnehin selber kennen.

Bei der Recherche bin ich allerdings auf eine sehr schlanke und smarte Lösung gestoßen, die ich abschließend noch kurz vorstellen will: Docco, eine kleines CoffeeScript. Bei Docco kann man im Configurations-File einfach ein paar Code-Dateien eintragen und dann per Befehl eine statische HTML-Doku genierieren. Die HTML-Doku enthält dann beides: Die Kommentare als HTML-Prosa und den dazugehörigen Quellcode.

Docco dürfte sich nicht nur für kleine öffentliche Code-Dokumentationen eigenen, sondern vielleicht auch für die schnelle Dokumentation eigener Code-Sammlungen in der lokalen Umgebung. Zudem wurde Docco inzwischen in zahlreiche andere Programmier-Sprachen portiert:

Name Sprache
Docco CoffeeScript
Groc CoffeeScript
Nocco .NET
Locco Lua
sourceMakeup PHP
Gocco GO
Marginalia Clojure
Pycco Python
Shocco POSIX Shell
Rocco Node.js

Soweit eine erste Übersicht und Einführung in das ganze Thema. Wie man sieht, passiert in diesem Bereich abseits der normalen Wahrnehmung eine ganze Menge. Und es gibt mit Sicherheit noch eine ganze Menge Lösungen, die hier überhaupt nicht aufgetaucht sind. Wenn ihr etwas Spannendes kennt, lasst es uns gerne über die Kommentar-Funktion wissen…

Wenn du ein Web-Projekt von A-Z erstellen willst, findest du im Themenüberblick viele Artikel zu jedem Schritt.