* Oliver Rath <[email protected]>: > Sehe ich genauso. Ich hätte es nur nicht so schön formulieren können wir > Pa@rick:-)
Vielen Dank für die Lorbeeren! :) Anbei ein unredigierter Artikel, der vielleicht dieses Jahr irgendwo in D erscheinen könnte. Vielleicht hilft das bei der Entscheidungsfindung. Er ist übrigens in AsciiDoc geschrieben… Dokumentation - was lange währt… ================================ Software ist ein Produkt. Ein Produkt ohne Dokumentation ist unvollständig. Das ist nichts Neues und auch die Tatsache, dass Entwickler - Ausnahmen ausgenommen - Dokumentation scheuen wie der Teufel das Weihwasser überrascht sicher niemanden, der in der IT tätig ist. Gründe für das gering ausgeprägte Bedürfnis, Software zu dokumentieren, gibt es viele. Dieser Artikel konzentriert sich auf die damit verbundenen Arbeitsabläufe und Werkzeugen - wie sie waren, wie sie heute sein können und warum es heute sogar Spaß machen kann, Dokumentation herzustellen. == Ausfuehrungsanweisungen Dokumentation ist Code. Code, der geschrieben wird, um z.B. Anwender zu mobilisieren. Mit Hilfe der Dokumentation sollen sie in der Lage sein, Software erfolgreich anzuwenden. Das dafür erforderliche Wissen muss erfasst, niedergeschrieben, in Form gebracht und mediengerecht verteilt werden. Guten Code schreiben ist schwierig. Es braucht eine Architektur, die der Aufgabe gewachsen ist. Der Code muss seine Funktionen eindeutig und fehlerfrei erfüllen. Der Code muss auf den Punkt kommen, damit er schnell und effizient ist. Redundanzen sind zu vermeiden. Wer programmiert und dokumentiert, weiß wie ähnlich und fordernd beide Domänen sind. Für die Programmierung haben Entwickler lange schon Abläufe und Werkzeuge entwickelt, die sie bestmöglich unterstützen. Sie standardisieren, versionieren und automatisieren wo immer möglich, damit sie sich auf die eigentliche Arbeit - das Schreiben guten Codes - konzentrieren können. == Broken Workflow Lange war das in der Welt der Dokumentation nicht so. Von Code-Dokumentation abgesehen, sah ein typischer Workflow für Print-Dokumentation in etwa so aus: Der Autor, meist der Software-Entwickler selbst, musste seinen Text in einem Word-Dokument verfassen, weil die Designer damit am besten umgehen konnten. Im Dokument musste er nicht nur Inhalt und Struktur entwickeln und kenntlich machen. Er musste auch durch richtige Formatierung darstellen, welche Worte Code, Kommandos, Kommando-Optionen usw. repräsentieren. Eine Gestalterin übernahm das Dokument, kopierte den Inhalt und fügte ihn in ein Adobe InDesign oder Quark Express Dokument ein. Dann setzte sie Absatz für Absatz, Wort für Wort von Hand. Das Ergebnis wurde dann als PDF an den Autor mit der Aufforderung zur Korrektur zurückgegeben. Korrekturen wurden als Kommentare in der PDF vermerkt. Auf diese Weise ging das Dokument solange hin- und her bis es fertig war. Standen grössere Veränderungen an, wurden Änderungen entweder Stück für Stück von Hand eingefügt oder das Dokument von Neuem begonnen. Nur in Ausnahmefällen bestand ein Workflow bei dem das Quelldokument in einem SGML oder XML-Schema verfasst wurde und dann nahezu automatisch mit z.B. Adobe Illustrator auf Grundlage vorgefertigter Transformationsregeln gesetzt wurde. Diese Art der Dokumentation war aufwändig, fehleranfällig und ineffizient. Die Autoren mussten nicht nur die zentrale Aufgabe meistern inhaltlich "gute Dokumentation" zu schreiben. Sie mussten den Inhalt auch gestalterisch richtig für die Designer vorgeben. Damit waren sie gefordert in einer Wissensdomäne zu arbeiten für die sie nicht ausgebildet waren. Fehler und Mißverständnisse waren vorprogrammiert. == Dokumentation wird Code Die Abkehr von Binär-Formaten und die Zuwendung hin zu Plaintext markierte einen wichtigen Wendepunkt. Jetzt war es möglich Dokumentation wie Programmcode behandeln. Der Text konnte versionieren, verteilt bearbeitet, gemerged und mit diff auf Änderungen untersucht werden. Die wichtigste Änderung war jedoch die Abkehr von Text der ein bestimmtes Aussehen trägt hin zu Text der eine bestimmte Bedeutung in sich trägt. Autoren formatierten ein Kommando nun nicht mehr als eine Zeichenfolge, die als "Monotype, regular, 12pt" dargestellt werden sollte, sondern sie markierten das Kommando einfach als "command". Das fertig ausgezeichnte Dokument übergaben sie anschliessen an die Designer. Diese wiesen den Auszeichnungen dann Formatierungen zu. == DocBook DTD Möglich wurde dies durch die Erfindung von DocBook einer DTD, die aus dem Umfeld des O'Reilly Verlages stammt. Ihr Erfinder, Norman Walsh entwickelte mit DocBook eine formatagnostische Auszeichnungssprache, die ein Vokabular (Elemente) speziell für technische Dokumentation zur Verfügung stellt. Mit ihr war es möglich Zeichen, Worten und Absätzen Eigenschaften wie "Kommando", "Datei" oder "Code-Beispiel" zuzuweisen. Anfänglich noch in reinem SGML formuliert, folgte bald ein XML-Schema mit dem der Quelltext von DocBook-Dokumente ausgezeichnet werden kann: [source,xml] ---- <article xmlns="http://docbook.org/ns/docbook"; xmlns:xl="http://www.w3.org/1999/xlink"; version="5.0" xml:lang="en"> <section> <title>Section 1</title> <para>A sentence with <emphasis>emphasis</emphasis> on a <command>command</command>.</para> <section> <title>Section 2</title> <para>An unordered list:</para> <itemizedlist> <listitem> <para>Item</para> </listitem> <listitem> <para>Item</para> </listitem> <listitem> <para>Item</para> </listitem> </itemizedlist> <para>A link to <link xl:href="https://example.com";>example.com</link>.</para> </section> </section> ---- Von diesem Rohformat aus, kann der Text in verschiedenste Zielformate überführt werden. Die Regeln des Zielformates werden dazu in einem XSL-Stylesheet niedergeschrieben. Mit Hilfe eines XSLT-Prozessors wurde das XML-Dokument dann unter Einhaltung der Regeln des XSL-Stylesheets "transformiert". Für eine man-Page (troff, ASCII text) genügte eine einfach Transpormation. Für PDF, RTF und andere Formate, wurde das Dokument in ein Zwischenformat, ein FO-Dokument, umgewandelt. Mit einem FOP (FO-Prozessor) wurde es von dort aus dann in das endgültige Zielformat umgewandelt. An dieser Stelle stagnierte die Enwicklung eine Weile. Das Handling der Quelltexte war einfacher und die Produktion von Zieldokumenten automatisierbar geworden. == Dokumentation 2.x Mit der Ankunft agiler Methoden stieg der Leidensdruck wieder. Dem Motto "Release early, release often" konnte Dokumentation nicht im erforderlichen Tempo folgen. Sie bremste die neue Arbeitsweise aus. Die Kritik am bestehenden Modell konzentrierte sich auf drei Aspekte der DocBook DTD: Komplexität, Konvention und Werkzeug. Der Segen der DTD, ihre Fähigkeiten und ihr Umfang, ist zugleich ihr Fluch. Wer mit DocBook arbeitet, muss sich auf ein komplexes Werk einstellen das es über längere Zeit zu erlernen gilt. Als XML-Sprache ist sie zudem strukturorientiert. Sie erwartet von Anfang an eine strukturierte Vorgehensweise. Damit setzt sie voraus, dass der Autor bereits beim Entwickeln des Textes eine klare Vorstellung von Inhalt und Struktur hat. Genau das ist aber so gut wie nie der Fall! Wer sich selbst einmal beim Schreiben beobchtet hat weiß, Form und Inhalt stehen zu Beginn nicht fest. Wesentlicher Teil der Schreibarbeit ist, Form und Inhalt iterativ zu erarbeiten und in eine der Argumentation dienende Abfolge zu bringen. Die Konvention der DTD behindert die Freiheit, die ein Autor zu Beginn benötigt. Und zuletzt waren die Autoren auf einige, wenige Editoren festgelegt, wenn sie das XML nicht nativ in einem Texteditor bearbeiten wollten. Gerade ihre textororientierten Editoren wollten die Entwickler nicht verlassen. == reStructuredText reStructuredText (kurz: rst) ist das Hausformat der Python Community. Mitglieder der Community sind gehalten Dokumentation (API, Code, Manuals, HOWTOs etc.) in diesem Format zu verfassen. Das populäre Buildsystem "Sphinx" geht nativ mit rst um generiert daraus HTML. Sphinx lässt sich in automatisierte Buildprozesse (Continiuous Integration) einbinden. Pygments sorgt für Highlighting von Source-Code Beispielen. .reStructuredText Syntax ----------------------------------------------- Section 1 ========= A sentence with *emphasis* on a ``command``. Section 2 --------- An unordered list: - Item - Item - Item A link to `example.com<https://example.com>)`_. ----------------------------------------------- rst ist so populär wie Python. Ausserhalb der Python Community ist es - gefühlt - genauso verbreitet wie das Versionsverwaltungssystem bazaar. Es war das gesetzte VCS in der Python Community, bevor diese letztlich dann doch auf git zur Sourcecode-Versionierung einschwenkten. Wer seinen rst-Quelltext in andere Zielformate unwandeln möchte, kann auf eine Werkzeugsammlung von Kommandos zurückgreifen, die alle mit rst2 beginnen. Sie stellen die gängigsten Formate man (troff), HTML, XML, LATEX und PDF zur Verfügung. Speziell sind Ausgaben für ODT und S5 (X)HTML Präsentationen. == Markdown Markdown ist die zur Zeit am weitesten verbreitete Variante einer Low Markup Language (LML). Seine Popularität hat es den Machern von github zu verdanken, die es zum Standardformat für READMEs etc. in ihrem VCS-Portal erhoben haben. Markdown vereint einfaches Markup mit den am häufigsten verwendeten Strukturelementen und inhaltlichen Auszeichnungen. Überschriften, Absätze, Listen, regular, bold, italic beherrscht es und auch Tabellen sowie Bilder baut es angenehmen einfach ein. .Markdown Syntax ----------------------------------------------- # Section 1 A sentence with *emphasis* on a `command`. ## Section 2 An unordered list: - Item - Item - Item A link to [example.com](https://example.com). ----------------------------------------------- Die zu Verfügung stehenden Sprachelemente sind allesamt generisch. Sie lassen sich auf beliebige Textformen (Brief, Dokumentation, Artikel, Blog etc.) anwenden. Und das ist, nach Aufassung der Autoren dieses Artikels, zugleich seine grösste Schwäche! In der Welt der Dokumentation und besonders in der technischen Softwaredokumentation existieren besondere Auszeichnungsformen, die Leser zum Beispiel auf besonders beachtenswerte Inhalte hinweisen. Gemeint sind Passagen, die mit Icons für "Info", "Wichtig", "Vorsicht" oder "Gefahr" besonders im Textfluss hervorgehoben werden. Die besondere Gestaltung dient als visueller Anker, der den Lesern helfen soll, den Gesamttext im Überblick zu "scannen". Es soll das Wesentliche schnell erfassen und wahrnehmen können. Der Leser soll maximal mit mobilisierenden Informationen versorgt werden, damit er baldmöglichst handeln kann. == Asciidoc Derartige Passagen und noch viele andere Sprachelemente beherrscht Asciidoc. Unter den heute gebräuchlichen Low Markup Languages ist Asciidoc das eloquenteste. Es weiß am präzisesten zu beschreiben was den Text alles auszeichnet. Seine Beredsamkeit kommt nicht von ungefähr. Es steht auf den Schultern eines alten Bekannten. Asciidoc ist ein LML-Adaption von DocBook. ----------------------------------------------- = Section 1 A sentence with 'emphasis' on a +command+. == Section 2 An unordered list: - Item - Item - Item A link to https://example.com[example.com]. ----------------------------------------------- Wer asciidoc Quelltext in andere Zielformate umwandeln will, kann auf zwei Kommandozeilenprogramme zurückgreifen - asciidoc und a2x. Das Erste generiert HTML-Ausgabe nach verschiedenen Standards in eine einzelne Ausgabedatei oder, nach Kapitel aufgeteilt, in mehrere Dateien. Das Zweiter bedient unterschiedlichste Ausgabeformate. Von RTF über PDF zu man-Pages (troff-Format) bis hin zu EPUB für Mobiles bedient es auch gehobene Ansprüche. a2x kann je nach Zielformat unterschiedliche Werkzeuge zum Generieren einbinden. Für PDF-Ausgabe können beispielsweise entweder der Open Source Apache FOP, kommerzielle Renderer oder auch Latex, über das dblatex-Tool, eingebunden werden. Möglich wird das bei PDF, weil a2x den asciidoc-Quelltext zuerst in das DocBook XML-Format umwandelt und dann - mit Hilfe von DocBook XSL - eine FO-Datei (Formatting Objects). Vor dort aus kann die .fo-Datei dann an beliebige FOPs (Formatting Objects Processor) übergeben werden. Diese rendern aus der FO-Datei eine PDF. Klingt kompliziert? Ist es anfänglich auch. Die Lernkurve bei asciidoc ist flach. Es dauert eine Weile, bis man zielsicher das richtige Werkzeug in der Kette bearbeitet, um die PDF-Ausgabe den eigenen Vorstellungen anzupassen. Dafür steht am Ende des Buildprozesses aber dann auch ein Dokument mit Titelseite, Inhalt-, Tabellen- und Bildverzeichnis, Index, Glossar etc. pp. Oben drauf auch gerne im hauseigenen Font - eingebettet in die PDF. == Buildchain Wer seine Buildchain auf LML umgestellt hat, will in der Regel noch weiter automatisieren indem er die Dokumentation zentral verteilt oder zum Beispiel Abonnenten der Dokumentation bei Aktualisierungen automatisch benachrichtigt. Hier bieten sich je nach Markup-Sprache Portale wie readthedocs.org oder gitbook.com an. Sie integriert sich in das eigene git-Ökosystem. Nach einem push ins Repository löst git einen Webhook im passenen Portal aus. Das aktualisiert (pull) die lokale Kopie des Repos und stößt anschliessend einen automatischen Build-Prozess für die Dokumentation an. Je nach Lizenzmodell, free oder Mietservice, benachrichtigen die Portal im Anschluss die Abonnenten der Dokumentation oder sie stellen den Abonennten die Dokumentation gleich per E-Mail zu. == Beyond Docs LML eignet sich auch für Blogs oder Websites. Die Inhalte werden lokal mit $EDITOR erstellt und bearbeitet. Je nach Website-Generator wird dann lokal eine Website "gebaut" oder die Daten werden zuerst auf den veröffentlichenden Server geschoben und dort wird die Website/das Blog kompiliert. Wer Kommentare in sein statisches Blog einbinden will, kann dazu disqus oder isso nutzen. Markupsprachen haben einen Wandel zur Reduktion hin vollzogen. Einfache und schnelle Bearbeitung stehen im Vordergrund. Jeder der genannten LML-Dialekte hat seine ganz eigenen Stärken. Das Notwendige beherrschen sie alle. Eine Lösung, die auf einfach Weise alle Aspekte abdeckt, existiert noch nicht. Zeitgleich hat sich eine Community formiert, die Dokumentation zum Thema hat. Sie ist offen und widmet sich den unterschiedlichsten Facetten (Tools, Strategien, Standarddokumente etc.). Nächstes grosses Treffen der Community wird die writethedocs-Konferenz vom 18. bis 20. September in Prag sein. EOF p@rick -- [*] sys4 AG https://sys4.de, +49 (89) 30 90 46 64 Franziskanerstraße 15, 81669 München Sitz der Gesellschaft: München, Amtsgericht München: HRB 199263 Vorstand: Patrick Ben Koetter, Marc Schiffbauer Aufsichtsratsvorsitzender: Florian Kirstein -- Abmelden und Archiv: https://lists.opensourcetreffen.de/mailman/listinfo/discuss Alle E-Mails an diese Liste werden unlöschbar öffentlich archiviert
