link

Td

Software: Eine Online-Dokumentation erstellen

Wer eine Online-Dokumentation, ein Benutzerhandbuch oder eine KnowlegeBase erstellen will, kann auf gute Open Source Software zurückgreifen.

Wer im Web eine Software oder einen Service anbietet, der ist mit einer nutzerfreundlichen Software-Dokumentation, einem Benutzerhandbuch oder auch einer web-basierte Knowlege-Base gut beraten. Solche Dokumentationen und Online-Hilfen sind für die Akzeptanz beim Anwender enorm wichtig und reduzieren außerdem die Anfragen an den Support. Zum Glück gibt es eine recht breite Auswahl an Open Source-Software, die die Erstellung und Pflege solcher Online-Dokumentationen erleichtern. Ein paar Beispiele.

Benutzerhandbuch mit Typemill

Eine naheliegende Lösung für Online-Dokumentationen ist der Rückgriff auf ein Content-Management-System (CMS). Das macht vor allem dann Sinn, wenn normale Redakteure oder Support-Mitarbeiter an der Dokumentation arbeiten und die Anwenderfreundlichkeit des Redaktions-Systems wichtig ist.

Für diesen Anwendungsfall wurde das schlanke Flat-File-CMS Typemill entwickelt. Das Open-Source-System basiert auf PHP und Vue.js und gehört mit wenigen MBs zu den leichtgewichtigsten Lösungen auf dem Markt. Gleichzeitig legt es mit einer Drag & Drop-Navigation und einem WYSIWYG-Editor für Markdown besonderen Wert auf eine autorenfreundliche Bedienung, denn gerade Markdown stellt normale Autoren hin und wieder vor leichte Hürden.

Typemill Animated Gif
Das Autoren-Interface von Typemill mit seinem WYSIWYG-Editor für Markdown

Typemill bietet verschiedene Themes und Plugins an, die einen flexiblen Ausbau des Systems ermöglichen. Die Systemanforderungen sind dabei minimal (Apache, PHP, keine Datenbank) und eine Installation ist auch von Nicht-Entwicklern leicht zu meistern. Das System wird unter anderem vom Hoster One für eine ergänzende Online-Hilfe eingesetzt.

An der Entwicklung von Typemill bin ich selbst maßgeblich beteiligt. Wer Unterstützung bei der Theme- oder Plugin-Entwicklung benötigt und gleichzeitig die Weiterentwicklung des Open-Source-Systems unterstützen will, kann mich gerne beauftragen. Inzwischen hat sich eine kleine Community rund um das System entwickelt.

Es gibt noch weitere Flat-File-Systeme, die sich für Dokumentationen eignen. Grundsätzlich können natürlich auch klassische Systeme wie WordPress, Joomla! oder Drupal genutzt werden, allerdings sind diese System deutlich überdimensioniert und für diesen Einsatzzweck eher sinnfrei.

CMS Kosten Beispiel und Bemerkungen
Typemill 0,- Verschiedene Themes für Dokumenationen und Knowlege-Bases.
Kirby 99,- Kirby-Lizenz Themes wie kdoc oder KirbyBook, die jedoch ggf. nicht mit Version 3 laufen
Grav 0,- Beispiel Grav-Doku mit dem Theme Learn2
Bludit 0,- Beispiel Bludit-Doku mit dem Theme Docs
Pico 0,- Mit dem Theme Bits and Pieces

Code-Dokumentationen mit Daux.io

Unter Entwicklern sind Static Site Generatoren für Software-Dokumenationen äußerst beliebt. Diesen Generatoren fehlt allerdings eine Autoren-Oberfläche. Sie sind daher für normale Autoren nicht geeignet. Bei den Static Site Generatoren werden die Inhalte direkt per Markdown erstellt und die HTML-Seite dann automatisch generiert, in der Regel per Konsolen-Befehl auf dem lokalen Rechner.

Auch die PHP-Software Daux.io gehört zu den Static Site Generatoren, allerdings erstellt Daux die Dokumentation aus den Markdown-Dateien on-the-fly, sodass man auf Konsolen-Befehle vollständig verzichten kann. Nur wenn man die Seite statifizieren will, muss man die Konsole bemühen und die statische HTML-Version mit einem kurzen Befehl erzeugen.

Der Dokumenten-Generator Daux.io
Schönes Design besonders für Code-Dokumentationen

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.

Speziell für Software- und Code-Dokumentationen gibt es viele Alternativen. Allerdings arbeiten alle anderen Static Site Generatoren ausschließlich mit Konsolen-Befehlen, außer Daux ist mir ist kein System mit einer Generierung on-the-fly bekannt.

Mit über 13.000 Sternchen dürfte Slate das populärste Tools sein. 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. Für PHP-Projekte bietet sich Couscous an, für die Python-Welt kann man auf MKDocs und Markdocs zurückgreifen. Relativ neu ist der von Facebook entwickelte React-Generator Docusaurus.

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.
Docusaurus React Von Facebook entwickelter Generator für Dokumentationen mit Markdown.

Software-Dokumentationen mit Sphinx

Sphinx ist eine Mischung aus automatischem Code-Dokumentator und einem redaktionellen Editor. Anders als bei dem rein redaktionellen Slate durchsucht Sphinx die Code-Dateien nach Kommentaren und generiert daraus eine automatische Dokumention.

Für den redaktionellen Teil setzt Sphinx nicht auf Markdown, sondern auf die Auszeichnungssprache reStrucutredText. Mit dieser einfachen Markup-Sprache werden kleine Text-Dateien erstellt, die von Sphinx mit Hilfe eines Templates in einen Web-Auftritt verwandelt werden. Sphinx ist bereits im Jahr 2008 entstanden und dürfte bis heute zu den beliebtesten Tools für Software-Dokumentationen gehören.

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

Name Unterstützte Sprachen
Sphinx Phyton, JavaScript, C, C++
Doxygen C, C++, C#, Fortran, Java, PHP
Javadoc Java
PHPDocumentator PHP

Dokumentationen mit readthedocs.io

Wer die Dokumentation 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.

Alternativen zu readthedocs gibt es einige. Speziell auf Bücher ist beispielsweise 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.

Name Sprache/System Beschreibung
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

Code-Dokumentationen mit Docco

Wer es eine Nummer kleiner haben will, der kann das kleine CoffeeScript Docco ausprobieren. Bei Docco werden in der Configurations-Datei einfach ein paar Code-Dateien eintragen. Anschließend kann man 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

Code-Dokumentationen mit 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.

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.

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