Vergangenes Meetup

Dokumentation schreiben kann Spass machen! (Sebastian Hempel)

Dieses Meetup liegt in der Vergangenheit

38 Personen haben teilgenommen

Bild des Veranstaltungsortes

Details

Woran liegt es, dass in den meisten Projekten und Unternehmen das Schreiben von Dokumentation einen so schlechten Ruf hat? Sicher nicht daran, dass die meisten Entwickler und Projektleiter das Wissen für sich behalten möchten. Auch der Sinn von der Dokumentation an sich wird nicht in Frage gestellt. Es sind die nicht für die Zielgruppe "Informatiker" geeigneten eingesetzten Werkzeuge.

Mit der leichtgewichtigen Auszeichnungssprache AsciiDoctor erfolgt das Schreiben von Dokumentation wie das Schreiben von Code. Der Entwickler nutzt den von ihm gewohnten Editor. Die Eingabe des Textes selbst erfolgt in reinem Text. Durch intuitive und leicht zu merkenden Auszeichnungen wird die Struktur und damit indirekt die Formatierung
des Textes festgelegt. Die Dokumentation kann wie Quellcode in einem VCS verwaltet werden. Wie Quellcode lässt sich die Dokumentation in verschiedenen Module / Dateien aufteilen.

Der Vortrag gibt einen Einblick in die Auszeichnungssprache AsciiDoctor und dem Programm zur Erstellung von Dokumenten im HTML und PDF Format. Es wird beschrieben, wie AsciiDoctor zur Dokumentation in Java (JavaDoc) verwendet werden kann. AsciiDoctor kann in die bekannten Build-Tools Ant, Maven und Gradle integriert werden, so dass die Dokumentation wie Quellcode regelmäßig übersetzt wird. Als Ausblick wird die Integration von "beschreibenden Grafikformatken" wie GraphViz und PlantUML in AsciiDoctor Dokumente gezeigt.

Im Anschluss zeigt Markus Harrer, wie auf Basis von AsciiDoc eine sich selbst prüfende Architekturdokumentation erstellt werden kann. Hierzu führt er kurz in das Werkzeug jQAssistant (ein Open-Source-Werkzeug zur statischen Codeanalyse) ein und dessen Integration mit AsciiDoc.

Speaker (Sebastian)
Sebastian Hempel ist selbständiger IT-Consultant und Trainer aus dem Fichtelgebirge. Seit 2003 unterstützt er Kunden bei der Entwicklung und dem Betrieb von Enterprise Anwendungen. Seine Schwerpunkte liegen dabei bei Java EE auf Linux Systemen.

In Projekten übernimmt er gerne die Konzeption und den Aufbau der Entwicklungs- und Build-Umgebung. In den letzten Jahren beschäftigt er sich mit der DevOp Bewegung. Neben seiner Tätigkeit als Softwareentwickler hält Sebastian Hempel Trainings im Bereich Java, Java EE und Puppet.

Speaker (Markus)

Markus Harrer arbeitet seit über zehn Jahren in der Softwareentwicklung an Hochschule, Forschungsinstitut und Softwareunternehmen. Derzeit ist er bei der Sparda Datenverarbeitung e. G. in Nürnberg beschäftigt. Hier entwickelt er Unternehmensanwendungen in Java und hilft durch die Analyse von Softwareartefakten, nachvollziehbar Verbesserungsmaßnahmen für Softwareprodukte zu erarbeiten. Seine Spezialgebiete sind Software Analytics, Softwaresanierung und Clean Code/Architecture.