Collaborative and Continuous Documentation mit LaTeX

Puzzle Tech Talk, 30. Oktober 2014, Zürich

Dr. Oliver SchmidSoftware Architekt

Aufgabenstellung und Tools

Aufgabenstellung

● Schreiben einer umfangreichen Spezifikation● Arbeit im Team (3-5 Personen)● Verschiedene involvierte Teilaufgaben● Requirements Engineering● UX● Architektur● Development

Variante A: Backseat-Driver(basierend auf Morris M.R. A survey of collaborative web search practices. In Proc. CHI 2008. ACM

Press (2008), 1657-1660)

Variante B: Bruteforce(basierend auf Morris M.R. A survey of collaborative web search practices. In Proc. CHI 2008. ACM

Press (2008), 1657-1660)

Variante C: Divide and Conquer(basierend auf Morris M.R. A survey of collaborative web search practices. In Proc. CHI 2008. ACM

Press (2008), 1657-1660)

PlantUML

LaTeX

Die Lösung...

LaTeX - Vorteile

● Konvertierbarkeit mit Pandoc (http://johnmacfarlane.net/pandoc/)

● Convert * to LaTeX ● HTML, RTF, DOCX, MD, ...

● Convert LaTeX to *● PDF, ODT, DOCX, HTML, RTF, ...

● Versionierung mit GIT● Verteilt (asynchrone Bearbeitung)● Fortgeschrittene Mergetools

LaTeX - Vorteile

● Vorgegebenes Layout● “Content first”● Corporate Design Anpassungen (auch rückwirkend)● pot. zentralisierte Styleverwaltung

LaTeX - Vorteile

● Dynamische Einbindung von externen Quellen● Immer aktuelle Sketches von MyBalsamiq● Stets aktualisierte UML-Diagramme von PlantUML

LaTeX - Vorteile

Demo

Da geht doch noch mehr...

● Unterschiedliche Generate● Unterschiedliche Dokumente für unterschiedliche

Empfänger● “Write once read anywhere”

LaTeX extended

● Einbindung in den Build-Prozessmechanimus (Continuous Integration / Continuous Deployment)

LaTeX extended

● Lebendige Dokumentation● Automatisierung so weit möglich● Nur aktuelle Dokumentation hat einen Mehrwert● Integration statt Durchsetzung von Standard-Tools!

LaTeX extended

● Glückliche Entwickler● Code-ähnliche Syntax● Auslagerung von wiederkehrenden Funktionalitäten

(DRY)

LaTeX extended

Mögliche Erweiterungen

● Unternehmensweite Dokumentation-Qualitätsstandards und deren Absicherung

● Einbindung von Wiki-Seiten in Generate

Mögliche Erweiterungen

● Screen-Recording von Frontend-Tests zur Use-Case-Dokumentation

● UML Reverse-Engineering (Modell-Aktualisierungen) und weitere statische Code-Analyse

● JavaDoc / Annotationsbasierte Dokumentation

● ...

Mögliche Erweiterungen

Q & A