In this presentation, the speaker will talk about his experiences, successes and failures with the arc42 architecture template in a DevOps team in a corporate environment with a product development focus.
Product development is often characterised by short iteration cycles and is therefore often operated in an agile manner, as in the speaker's team. There the existing unstructured documentation was transferred to the arc42 template and stored in a wiki. In the course of time, it turned out that tooling plays a decisive role for the quality of the documentation and therefore switched to Docs-as-Code.
In the course of the presentation, the most important decision points for the current iteration of the technical software architecture will be discussed. These include the handling of "developer prose", outdated documentation and the architecture decisions that are particularly important for a DevOps team. The integration into the methodical procedure Kanban was made possible with arc42 and a microsite based on AsciiDoc.
Not left out are the mistakes made, such as missing quality assurance of created documentation or the mixing of business and technical topics.
3. DB Content Hub
DB Systel GmbH | Johannes Dienst | @JohannesDienst 3
‒ Content as a Service (CaaS)
‒ Headless CMS
‒ Self hosted in Cloud
‒ You build it, you run it!
5. The Cost of Poor Documentation
DB Systel GmbH | Johannes Dienst | @JohannesDienst 5Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
6. The Cost of Poor Documentation
DB Systel GmbH | Johannes Dienst | @JohannesDienst 6Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
8. arc42
DB Systel GmbH | Johannes Dienst | @JohannesDienst 8
Building Block View
Deployment View
Runtime View
arc42
1. Introduction and Goals
2. Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Deployment View
7. Runtime View
8. Concepts
9. Architecture Decisions
10. Quality
11. Risks and Technical debt
11. Glossary
9. Technical Architecture in a Devops Team
DB Systel GmbH | Johannes Dienst | @JohannesDienst 9
Betriebshandbuch
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
10. Must Haves
DB Systel GmbH | Johannes Dienst | @JohannesDienst 10
‒ Introduction and Goals
‒ Constraints
‒ Context and Scope
‒ Solution Strategy
‒ (Building block view)
‒ (Deployment view)
‒ (Runtime view)
‒ Concepts
‒ Architecture Decisions
‒ Quality
‒ Risks and technical Debt
‒ Glossary
11. Glossary
DB Systel GmbH | Johannes Dienst | @JohannesDienst 11
Content
Asset
Content
Type
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
12. A Wiki Is Born
DB Systel GmbH | Johannes Dienst | @JohannesDienst 12Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
13. Technical Architecture Documentation!= Tutorial
DB Systel GmbH | Johannes Dienst | @JohannesDienst 13Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
14. The Wiki Is a Problem Child
DB Systel GmbH | Johannes Dienst | @JohannesDienst 14Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
15. The Wiki Is a Problem Child
DB Systel GmbH | Johannes Dienst | @JohannesDienst 15Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
16. Switch to Docs-As-Code
DB Systel GmbH | Johannes Dienst | @JohannesDienst 16Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
17. Advantages of Docs-As-Code
DB Systel GmbH | Johannes Dienst | @JohannesDienst 17
VonFreeSoftware
Foundation-[1],FAL,
https://commons.wikimedi
a.org/w/index.php?curid=
53428398
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
18. Advantages of Docs-As-Code
DB Systel GmbH | Johannes Dienst | @JohannesDienst 18Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
19. Advantages of Docs-As-Code: Docs Review
DB Systel GmbH | Johannes Dienst | @JohannesDienst 19
main
adr-042
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
20. AsciiDoc > Markdown
DB Systel GmbH | Johannes Dienst | @JohannesDienst 20
Standard
Includes
Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
21. Documentation in the Corporate Environment
DB Systel GmbH | Johannes Dienst | @JohannesDienst 21Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
docToolchain
24. Outdated Documentation
DB Systel GmbH | Johannes Dienst | @JohannesDienst 24Icons made by Freepik, Good Ware, Sprang and Smashicons from www.flaticon.com
25. Architecture Decision
DB Systel GmbH | Johannes Dienst | @JohannesDienst 25
Building Block View
Deployment View
Runtime View
arc42
1. Introduction and Goals
2. Constraints
3. Context and Scope
4. Solution Strategy
5. Building Block View
6. Deployment View
7. Runtime View
8. Concepts
9. Architecture Decisions
10. Quality
11. Risks and Technical debt
11. Glossary
26. ADR-003: Staging- vs Cluster-Environment for CMS
We use two environments (IAT, Prod). These are set up as clusters.
DB Systel GmbH | Johannes Dienst | @JohannesDienst 26
Status
Accepted
Context
A solution is sought to ensure scalability for the entire system. The goal is to potentially serve dozens of
customers with thousands of requests per second.
Consequences
Change of system architecture necessary
‒ Dismantling of the two public instances
‒ Deconfigure push publishing
No environment is provided on which content is pushed
Alternatives
Cluster-Solution
‒ Operation of the CMS in the cluster -> Horizontal Scaling
Push Publishing
‒ Vertical Scaling
28. DB Systel GmbH | Johannes Dienst | @JohannesDienst 28
Which two questions are still open?
Johannes.Dienst@deutschebahn.com
@JohannesDienst
29. DB Systel GmbH | Johannes Dienst | @JohannesDienst 29
Links
https://arc42.org/
https://leanpub.com/arc42byexample
https://www.dokchess.de/
https://github.com/joelparkerhenderson/architecture_decision_reco
rd
Hinweis der Redaktion
Schnelllebig durch kurze Iterationszyklen
Fehler werden gemacht und daraus wird gelernt
Kostendruck
Agile Entwicklung im DevOps-Produktionsmodell
Kundenorientiert (Muffin)
Schnelllebig durch kurze Iterationszyklen
„Dokumentation ist nicht agil“ -> Talk von Kevin Goldsmith verlinken
Hinleitung auf nächste Folie: Warum ist Dokumentation denn wichtig?
Warum dokumentiere ich eigentlich? ->
OnBoarding sonst zeitintensiv,
Zertifizierung im Konzernumfeld
Für andere Teams
„Für mich selbst“
Frage stellen: Wer kennt arc42?
Hier noch nichts drüber erzählen, warum das gerade für DevOps-Teams gut ist!!!
Kommt auf nächster Folie
Arc42 eignet sich perfekt für DevOps-Teams
* Struktur ist immer gleich -> Schnelle Einarbeitung
* Leichtgewichtig: Nicht alle Kapitel müssen ausgefüllt werden
* Dokumentiere, was du lesen willst
* Kapitel teilweise wiederverwendbar in Betriebshandbüchern
Hier erläutern:
Einführung und Ziele
Randbedingungen
Kontextabgrenzung
Querschnittliche Konzepte
Haben wir nie ausgefüllt -> Immer wieder reden wir aneinander vorbei
Leicht zu benutzen
Leichtes Setup -> Einfach bestellen und schon ist es da
Erwartung: Da wird mir die Welt erklärt!
Oft Tutorialähnliches in arc42
Lieber in Readme des Repos
Wiki hat folgende Probleme
* Information geht da zum Sterben hin: Symbolisiert Icon 1
* Jeder kann einfach Braindumpen -> Entwicklerprosa Icon2
* Kommentarfunktion
* Vermischung von fachlichen und technischen Themen
Was fehlt noch? Siehe nächste Folie
* Kein Review -> Qualität ist schlecht
* Versionierbarkeit?!
Stressen, dass das Tool der entscheidende Faktor ist, ob Dokumentation genutzt wird oder nicht!
Was ist das überhaupt?
Entwicklerwerkzeuge
WYSIWYM -> Plain Text (Endlich kein Formatierungskrieg mehr!)
WYSIWYM -> Plain Text (Endlich kein Formatierungskrieg mehr!)
Entwicklerwerkzeuge
Qualitätssicherung über Feature Branches
WYSIWYM -> Plain Text (Endlich kein Formatierungskrieg mehr!)
Warum Liebesgeschichte?
1. Jedes Kapitel in eigene adoc-Datei
2. Kann diese Dateien dann zusammenincluden wie ich will
Kann nicht nur geforderte Dokumente daraus generieren
Sondern auch Microsite:
- Leicht Indizierbar in interner Suchmaschine
- Einfach durchsuchbar
- Angenehm zu benutzen
Wegwerfen, da im VCS noch vorhanden: Wie geil ist das denn?
Feste Termine einplanen, um die Architektur immer wieder glattzuziehen: Geht leider nicht anders
Für unser Team fast das Wichtigste
1-2 Minuten etwas darüber erzählen
Für unser Team fast das Wichtigste
1-2 Minuten etwas darüber erzählen
Für unser Team fast das Wichtigste
1-2 Minuten etwas darüber erzählen