 Hello, everyone. My name is Johannes Dienst. Normally, I hold this talk with Karsten Hofmann, a colleague of mine. Combined, we have an experience of over five years of real DevOps in our corporate environment. And we learned two things you might want to hear about, because they can help you develop better services, implement faster and be happier in your team. So let's get it on. The table of contents is very small today because I only have 20 minutes. So we start with an origin story, where we come from, what we really mean by doing DevOps. Then we jump right into the problems we faced, which were quite different, but the same for both our teams, namely knowledge silos and documentation. So where do we come from? We come from a company called Deutsche Bahn. A subsidiary of it is Davis Estelle, where we both work for in different teams. And since 2008 and before, we are the digital partner of Deutsche Bahn. We are driving the digitalization of the Deutsche Bahn. And in 2018, there came a mind shift. We had development and ops separated. And then we said, okay, it's better to develop services and produce them in the DevOps production model. So what do we mean by DevOps production model? Yeah, DevOps is pretty easy, but everybody understands something different for it. We understand that Davis is still about DevOps. It means you build it, you run it. And this really, we're talking to the customers, especially in my team, we're talking to the customers and hear what they want from us. And then we implement our service. We are bringing it to production and we are taking it into operation. I'm developing in my team a product called DB Content Hub, which is a CMS, a headless CMS with an API on the platform that the team of Carsten Hofmann provides, named the business hub, which is basically an API management platform. And they're also doing it at DevOps production model. So they bring some features in production and run it. And it's interesting, when we prepared the talk, we discovered that we had the same problems. So it's interesting. And then we said, okay, we prepare this talk and these two problems were the main problems we faced, namely knowledge silos and documentation. Also, let's start with the knowledge silos and start with the Carsten's team. Carsten's team was hacking away happily at the start. And then everybody was using their own tools. And they discovered, oh, yeah, everybody's using their own tools. And own tools doesn't mean IDEs, but really the tools, the frameworks. For example, there were enterprise architect for documentation, there were drawer for documentation, there was a Visio for documentation. There were different build systems altogether, Maven, Gradle, different languages, JavaScript, Kubernetes, JavaScript, Python, Java, different platforms they deployed to Kubernetes and OpenShift. And this created a big problem because everyone wrote code that other team members couldn't maintain. And if you're in a small team and someone fails, for example, someone gets ill, gets sick, then the others couldn't provide the service he provided. And if you're in production and have to fix a bug and you can't fix the bug because you don't know the tools, that's a really big problem. So they had a tool explosion on this side. We had a tool explosion on the IDE side. So for example, we were five developers and everybody used their own IDEs. So there was one sublime guy. He is a little bit older, though he uses sublime, but he's very proficient with it and very productive. Then we had two IntelliJ guys, which were media colleagues. And we also had two guys with Visio Studio Code background, with JavaScript background and they used Visio Studio Code, which is all fine. They all do the same thing. But on top of that, we also had the same tool explosion of like Castance Team. Like we had JavaScript, TypeScript, and Java. That's not as much as Castance Team, but it was as much if you work in a DevOps team. And then we had for documentation, for formats, draw IO for diagrams. Then we had ASCIDoc. We had also Markdown in our repositories. And sometimes you also use the word and sometimes a wiki. I haven't mentioned it there because wiki is a little bit like ASCIDoc and Markdown. And what we discovered was there is a high mental load. And there's also a high mental load if you're the one sublime user and your IDE is not functioning as expected. So the IntelliJ or Visio Studio Code guys can't help you. That's okay, but you have to deal with problems in your IDE alone. That's a problem. That's a real problem. And also the context switching is very, very high. So if you're programming JavaScript, Java and TypeScript, and then you're documenting ASCIDoc and sometimes Markdown, you also have to remember so many things. For example, ASCIDoc is a little bit similar to Markdown, but different. So you have to context switch all the time in languages. And this creates a high mental workload. And finally, we also discovered we had a lot of legacy code, legacy documentation, because our work base became unmaintainable. So what do we do? What did we do about it? And we came to the same conclusions. In Carsten's team, the team came to the conclusion. So we are producing artifacts. And everybody should be able to produce these artifacts, for example, documentation or tests. So everything that produces an artifact should be a team decision, finally. And they decided, okay, perhaps we want to use Enterprise Architect, but it's not good if somebody can't use Enterprise Architect. So it's always a team decision what we use for documentation because this creates an artifact or what we use for tests. So they decided, okay, draw is for documentation. ASCIDoc is our markup or markdown language. And we have rest assured for tests. There were many more tool decisions they made, but this is the basics. And we didn't went the same way in our team, but we came to the same, to a different, but same conclusion. Okay, we have all these different IDEs and that's okay. It's fine. Everybody should use their own ID. But if you're producing tests, for example, then you have to produce this in the most basic technique that is available. And the most basic technique available, for example, we are developing an API, which is also on the API platform of Carsten's team. Then we're doing API calls. And the most basic technique for API calls is Curl, so Bash. And we put all these example code in Curl, in CurlCourse, and everybody can use the Bash. And then we're fine. If you want to use your own tools, like for example, Postman or Plugins for your ID, that's totally fine, no problem. But you have to create it on your own from Bash. And what we also discovered is, okay, no project files of IDEs in the repository. So we created an Gitignore, which rejects project files. And that's it. That was our solution for it. And as Carsten's, okay, we have one tool for one job, we came up with the most basic technique, which is practically the same. Then in a DevOps team, should you document? I would say, yes, you should document. But everybody fears that way. And documentation is all sometimes a drag, especially in a corporate environment. Why is it a drag in a corporate environment? Yeah, the corporate environment urges us to use Word. We have to use Word. And we have templates for architecture documentation, for example. That's fine. But the templates are often bloated. And so you fill in a lot of information you might not need. So you have bloated Word documents with information you need and a lot of information you might not need. And that's not very pleasant to work with, especially if you want to move fast. So that's one problem. There's another problem. It's not linkable. You can put links in Word, but you also have to download the Word to feud. So links in Word do not really work out the way it should be. Not the way you think about it in HTML, for example. So okay, you have interface definition. And it costs another interface to fulfill the job. So you have to download the Word. That's not very cool to work with. Also, I can rent about Visivic editors all day long. But every time I touch a Visivic editor and Kastner showed me, he feels the same way. It just doesn't do what you expected it to do. For example, if you have a heading and you press enter, then the new line sometimes it's also heading and sometimes it's standard and it's not deterministic. So editing a Word or for example a Wiki is very tedious over Visivic because sometimes you just trash the document and it's gone. This can't happen with, for example, text-based editing languages like Markdown or AskingDoc. And also versioning. Versioning documentation in Word is a pain. You can't do it. Perhaps you have a system who can't do it, but it's not automatic. You can't automate it most of the time because there should be an API for this tool and this tool often these tools don't have an API for it. So we decided, okay, if we need to have an output Word, then that's okay. We can create it, but we don't want to use Word. It's our main documentation language. That's what we both came up with. So what do we do now? There's an old new approach. For me, it's a little bit older because I use it for two years now. It's called the DocsisCode approach. So you treat your docs like code and code is basically text. So I'm pretty sure everybody of you knows Markdown, but we came up with a solution we said we want to use AskingDoc. Why won't we use AskingDoc? Markdown has a problem called standard. It's a very small standard Markdown. And AskingDoc has a very rich standard and there's basically only one standard. And if you have a small standard, like a small specification, like Markdown, everybody creates their own flavor and the flavors don't interoperate very well because their own flavors. And that's not the problem with AskingDoc. Every AskingDoc implementation is the same because there's only one specification that's feature rich. That's cool. You can copy AskingDoc everywhere and it works. So AskingDoc is a cool choice. There's another feature called includes. We have a technical architecture documentation in Arc42, for example. If we need the glossary in the user documentation, for example, then if you have a word, you have to copy it. You can't include it. AskingDoc has this cool feature where you can modularize your documentation. With this modularization, you can say, okay, if I need a user documentation, I need this glossary from the Arc42 technical architecture documentation. Yeah, then it's fine. I just use the include phrase. And when the AskingDoc gets rendered into an HTML or PDF or whatever format you like, then this gets included and it looks like it is in this document. But you only have to gardening it in one place. That's a major plus. It has includes AskingDoc. And also the tooling. The tooling got better in the last two years, namely because of plugins. In Visual Studio Code, for example, you have a very cool AskingDoc plugin. I use IntelliJ mainly. And it has an AskingDoc plugin, which is beyond everything. It has autocomplete functionality, preview functionality. It's AskingDoc feels like a development language if you use the IntelliJ plugin. So highly recommended. Just Google AskingDoc plugin from Alexander Schwarz. And if you treat docs as code, then it's text-based. And you put your docs into a Git repository, for example. And then it's easily versionable. And the versioning is also automatable. But that's again, it's automatable. Every time you push something to production, you can create a new version by attack, for example, or by a new commit. And you can check that out easily. Just check out the tag. It's already there. Git gives you everything you need. So that's a major plus. You don't have to do this versioning alone. So how does this integrate in our workflow? Yeah, I already mentioned it's modularizable. And what we do in Carson's team, they do it extensively, they say, okay, we put every documentation with the coders. So we have different Git repositories and put the documentation with the coders. And in our team, we didn't start there. We all put all our documentation in one place. But now we're writing operations manual to discover that it's better to put the documentation, for example, for the deployment of a service or for deployment of an artifact into the repository itself. We decided, okay, we put the documentation also in the Git repositories where the code is. And it's pretty easy to create an overarching repository, the one here on the left side. And just check out in the build process, the sub-modules, for example, the Git sub-modules, and then include them in the ASCII doc. It's pretty easy. And if we do this, we can create all sorts of documentation and renders in all sorts of formats. And there's one open source tool called doctoolchain. There are other open source tools like Pandoc, for example. We use doctoolchain and GitLab CI-CD to create all different formats of our documentation. So if we need a word, there's no problem. Doctoolchain can create a word. Or if you need a PDF, you can also style your ASCII doc in your corporate CI-CD. No problem. And create a PDF from it. It looks like it was created from Word. And the third approach is we use to create a microsite, HTML site from our documentation. And Kasten does this as well. He doesn't use the microsite. They use a homebrew framework, but it does the same. Don't bother. It's in German, but you will understand what it means. And you can create an HTML site with GitLab CI-CD and GitLab pages with static site generator. And this static site generator has a lot of great features, namely it creates HTML and a little bit of JavaScript. It's blazingly fast to create an up-to-date version. You can automate it with GitLab CI, so every time the new production version comes out, out of the documentation changes, the microsite gets rendered at you. And then you have all your documentation in one place as an HTML site. And an HTML site is highly accessible. Everybody can read it. It's not like a Word document in some obscure system and nobody can find it. An HTML site, if you integrate it in your internal search, which we have at Devious Estelle, it's Deutsche Bahn-Wide search engine. It's integrated with a search bot, and the search bot just crawls it. It's basically a web crawler. And it's an index of the search site. You can find our documentation easily if you just type in, for example, dbCondent up the product we develop. And everybody has a browser and everybody can read it. So if you're doing documentation, this docs is code, and with a microsite, you get a lot of benefits out of it. So I'm already at the end. To recap, I talked about knowledge silos and how you can conquer them. Remember, everything that creates an artifact should be a team decision, or you use the most basic technique like in our team. And if you're doing documentation at DevOps Team, please use docs as code. It has so many benefits. Then I can't even name it. I don't want to go back to Word. So this was it. You learned something you can immediately apply. And I hope you enjoyed it.