Docs-as-Code

Technische Dokumentation sollte man nicht mit Textverarbeitungsprogrammen erstellen. Stattdessen macht es Sinn, sie in die normalen Entwicklungsprozesse einzubeziehen, die Erstellung zu automatisieren (Continuous Documentation) und mit den typischen Werkzeugen der Entwickler, sowie mittels leichtgewichtigen Textformaten zu bearbeiten (Documentation as Code).

Mit docToolchain gibt es bereits eine ausgereifte und effiziente Lösungssammlung basierend auf AsciiDoc und Gradle. Dabei zeigt docToolchain zwar fertige Lösungen auf, soll aber in erster Linie demonstrieren, was alles möglich ist. Jeder ist eingeladen, den Ansatz zu erweitern und an seine Prozesse und Vorgehensweise anzupassen.

Transcript

1. Ralf D. Müller, Falk Sippach 8.4
2. Ralf D. Müller Ralf D. Müller Solution Architect Groovy und Grails Fan-Boy arc42 Contributor Maintainer von docToolchain 8.4
3. Falk Sippach Falk Sippach Trainer, Architekt, Entwickler Orientation in Objects GmbH JUG Darmstadt und JavaLand DukeCon Committer 8.4
4. Architektur dokumentieren? Architektur dokumentieren? 8.4
5. Warum dokumentieren? Warum dokumentieren? 8.4
6. Dokumentieren nervt! Dokumentieren nervt! Falsche Werkzeuge (WYSIWYG) Dateiablage im Share-Laufwerk Redundanzen Textwüste Handarbeit Veraltet Liest sowieso keiner! 8.4
7. 8.4
8. Unser täglich Brot … Unser täglich Brot … 8.4
9. Demo Demo 8.4
10. 8.4
11. 8.4
12. 8.4
13. 8.4
14. Docs-as-Code Docs-as-Code 8.4
15. Teamwork Teamwork 8.4
16. Automation Automation 8.4
17. docs-as-code implementiert docs-as-code implementiert 8.4
18. docs-as-code implementiert docs-as-code implementiert 8.4
19. docs-as-code implementiert docs-as-code implementiert 8.4
20. docToolchain docToolchain github.com/docToolchain 8.4
21. kombiniert mit… kombiniert mit… 8.4
22. Fazit Fazit 8.4
23. 8.4
24. Werkzeugkette Werkzeugkette 8.4
25. Inhalte je Zielgruppe Inhalte je Zielgruppe 8.4
26. Verschiedene Ausgabeformate Verschiedene Ausgabeformate 8.4
27. Plain-Textformate Plain-Textformate 8.4
28. Grafiken im Textformat Grafiken im Textformat [plantuml,"stage3",png] ---- database Repo as git database Fork as fork file .html as html file .adoc as adoc actor you as you actor team as team git <--> adoc you <-> adoc [AsciiDoctor] -> html team <-> fork fork <- git: clone fork -> git: PR node "Build\nServer" as bs git -> bs: "on change" bs --> [AsciiDoctor] ---- 8.4
29. gerendered gerendered 8.4
30. Ausblick Ausblick 8.4
31. Dokumentation generieren Dokumentation generieren 8.4
32. Ausführbare Dokumentation Ausführbare Dokumentation 8.4
33. 8.4
34. 8.4
35. Danke für Ihre Aufmerksamkeit! Fragen? @ralfdmueller @docToolchain @sippsack 8.4