 One of the least productive things you can do is context switch. When you switch tasks, particularly if you're switching tools as well when you do it, you reset your contextual flow and that has a very real, very measurable effect on your productivity. Now when you migrate from a DIY tool chain to a more comprehensive DevOps platform, you are eliminating not just integrations that you need to manage, but also a huge amount of that switching costs, and you're giving yourself the opportunity to build a better, more comprehensive and productive flow. And one example of that is documentation. In our next talk, Philip Westfallen and Benedict Stimmelt will discuss their journey toward making the developer documentation process as fun and as fluid for developers as the coding process that they were already following. Let's hear what they have to say. Welcome, everyone. We will share a little bit about our way, how we bring the documentation back to the fun level. So documentation is that long-lived documentation. Yes, me. My name is Philip Westfallen. I'm from Hamburg, work for the Flores online shop and yeah, I'm a software engineer there. And a part of that I manage the GitLab Meetup here in Hamburg and I'm also a GitLab hero. Hi, thank you, Philip. My name is Benel or Benedict or Ben, whatever. I'm the CEO of the same company, Blumen 2000 AG. We are a handbook-based company, as you already thought because of Philip doing the Hamburg Meetup. I've been using GitLab for a while now and I'm not a hero, but maybe in the future I will be. I don't know yet. You can see my handles here. I'm a passionate software developer and I'm still trying to get into the code whenever I can, discussing architecture. I love that very much and documentation is always a part of architecture as well. So yeah, we thought let's dig into that topic. It's always a little bit hard to speak about it. But yeah, I think we have a good way of showing you what we like about documentation. Let's head back to Philip. He will start. We will start with a daily disaster with documentation. So we're describing first why writing documentation makes no more fun to us and now he starts with the product owner view or non-technical person view. Yeah, right. So you probably guessed it by now. We're trying to switch between the robots. I'm doing the non-deaf role as it is most of my time in the daily business as well. And Philip is doing more or less of a deaf view. Yeah, what you can see here is my daily what the heck moment when opening Confluence or any other documentation tool like Confluence, but it's always a good example. It's not that. Yeah, it's not what you would have expected from a documentation. So I've picked a random page from our Confluence and what you can see here is a little smaller view like 13 inch display. And then the half you can read anything. It's no structure. It's like a lot of white space, no information there. No one knows what's going on. It's very hard to motivate people writing that it's very hard to focus on the content. Most of the time you focus on on the layout and making it somewhat readable. You all know that. And as you can see here, someone really thought through publishing the page. I don't know what happened there. It's a very big accident. And then enough of that there's no testing. You cannot see what changed during the documentation very well. So yeah, I don't like it very much. You all know that, but somewhat I don't know why it's in the comfort zone for most of the PO's. They tell them, yeah, let's document stuff. They first thing of Confluence. So that's the PO view. Let's take it over to the deaf view. Yeah, for me as a developer, the writing documentation feels mostly boring. I have to head to the web page and type something into Confluence. So it's feeling like a shore because I'm wanting to write code and do the fancy stuff. And yes, and I mentioned before, yeah, we have to move out of our fancy IDE and jump into a tool which is full blown like Word document editing. And yeah, you have so much things to do to bring a good looking documentation. And when I'm my truly passion is or my truly passion, it's my comfort zone as a developer is marked on. So this is everything I need. I have code like structuring my content. And this is everything I need. And I don't need a full blown tool to write our documentation. Yes. So this was our pain. And now we switch to our dream world, I think. Yeah, that's correct. So I think you can relate a lot to what we told you about here in this fast example. So we wanted to get to catch you and not waste too much time on it, but there's so much to tell about the disasters and the pain. But you all know it, right? So let's move away from the pain to the good parts, right, to the light. And for us, at least from a feature point of view, it means that we have a light white tool that is not overgrown with buttons and stuff and you can do this and that and whatever. And you don't need like 90% of that things. And that's why we want to focus on the path that's necessary. So that's why writing good looking documentation needs to focus on creating content and not layout, right? So nowadays, you spend like 90% of the time making it look good and 10% putting the information in there. And that should definitely switch around. So 90% getting the information in there and 10% making it look good. And to make that happen, you need because I'm not a documentation pro and I think Phil isn't as well. So we are developers, right? And we are not technical writers or something. So we need guidance and structure. So the tool should give us that so that confluence is like there's no guidance, no structure at all. So you're lost in there and the tool should guide you, should help you from one of you. And let's look like a little bit of, so we are not trying to bash that much, but the search is like key feature to find stuff in the documentation. Navigation isn't that important to find stuff. Navigation is giving structure. But if you're looking for something, what was the VPN setup like, then the search should be pointing you exactly there. And not like, oh, here are 50 pages talking about somewhat with a V and a P and an M in there. Maybe you look there. So that's, yeah, that doesn't help. So all in all, it just should be fun to write the documentation. It should be easy to read it. It should be fun. And to make that happen, Phil is talking a little bit about the requirements. Yeah, the requirements are quite a lot because we have two worlds colliding, the dev and the POs. So it's mostly important that we find a tool, which is lightweight and especially the language where we are writing them. For example, the markup should be simple and easy to learn and intuitive. And so the language must provide the basics like we have to add links and pictures and tables and whatever you need in a basic set. But also features are important like code blocks because we are writing sometimes technical guides, where it's important that we can choose a language of the programming language and to structure that good. So it's feel cool. And yeah. And these were the requirements for the language or the style we need. And the tool itself needs some essential features. Bina mentioned it before, search is the most important thing. Especially that you don't only search for headlines or... Yeah. Search. You have to search the whole content to find your related information you need. Yes. And navigation should be also very simple. So it feels native to build a structure or in the best case, it should be done by the directory structure. Yes. And another very important thing is that you can write the documentation in the web, like in the web IDE of GitLab or as a developer in the local IDE or whatever you want to do in the repository locally. And the editing process should be... Yeah. It should be easy. You only edit one page and you are done. And yes. And another thing which is important. It should be a home where you can access anywhere and everything. So even when you are on a smartphone or at the desktop, you should be using the tool very good. And yes. And when it comes to local writing documentation, a really cool feature would be that you have live feedback. So when you are editing the documentation, it should be shown immediately. And the web browser is rare. It's documentation rendered. Yes. And nobody likes maintaining and hosting. So the tool should be really easy to maintain and to host. Yes. These are, as a developer view, the most important thing. Yes. I get that. So we have the product owner perspective, the dev perspective. I think you all also think that that's a good start or maybe have some advanced features you need. But for us, this was the set we needed. And obviously tools like Confluence and such provide them, but not in the light-white fashion. So it's all in there, but it's very hard to use. And we'll get there and show you some examples of tools we are currently using. But first, let's make a short excourse on what you actually should write into your documentation. And some of you might thought, hmm, I don't run to write documentation at all. Like, let's just generate all this stuff. And I was a big fan of that as well. But as more as I thought about architecture and people and communication in general, I got used to or I got fond of the idea that it's very hard to generate documentation. Because it's like code formatting. You don't write pretty code because the computer wants you to do that. You want that so that other developers can read it better and see the structure very well and get started immediately with coding and not just first have to, like, platter all this stuff and then find out, wow, it has someone done here. And for me, this is the same with documentation. So if I generate documentation, it's very hard for a human to read it. It's easy for a machine to read it. Obviously, there are some use cases like shown here in this picture where you can generate the documentation and you should because it's, you document a very structured thing that can be very easily generated into a structured documentation. It's very near to the machine, right? Like a REST interface, like you can see the open API standard documentation. And that's pretty easy to generate that. But like generating a class diagram for me has no value at all. Like I can go into the code and generate it myself or I can like see the Java documentation which is on there. So most of the time I think about what is the audience for my code and for my documentation and for my code and what would that audience maybe need to understand the code. And the code itself shouldn't have any comments and stuff like that because it should be self-explanatory, right? So very well-named methods, not the topic for today. But I don't need to document that because it's already documented itself. But I need the context around that. Maybe the purpose of the code, what am I doing here? Everything that's not in the code itself. And I can't generate that because it's not in the code itself, right? So maybe you think about the generating stuff in a different way after that or you've got an idea of what I'm talking about. So what we did, we focused on the not generating part here, right? So we needed a tool for writing the stuff ourselves. And obviously we bashed a lot on confidence until now. So let's have a look at which tools we like and we use. Yeah, we explored some tools which met our requirements or we know they look great in the real world. Yeah, and the first tool is ViewPress. It's most commonly known that it's the documentation of Vue.js. And it's written in Vue.js, which is cool because we write our online shop in Vue.js. So we could extend the documentation if we have more advanced needs. Yeah, and it's a basic side generator. So we have files or have our structure, yeah, have our structure of our documentation somewhere and it's print out HTML documents in the end where we can put anywhere. Yes. And the cool thing about that is it's written or you write your documentation and markdown. So it's provide everything you need. You know how markdown works because it's everywhere in GitLab, like in the GitLab issues. So we have to daily deal with markdown. So it's commonly known. Yeah, and it got us a good search about over the content, what's in the documentation. Previously it was only in the headlines. But they released version two some weeks ago. And now you can search additionally in the content. So it's improving and a good living tool. Yeah, and also it has a great performance. It's really fast because it's Vue.js in the background and it's really simple to use. Yeah. And it simply generate our documentation very well for every user. Sounds like a good tool, right? Yes. So let's look into an alternative. So actually there's not that much difference in the core concept of the tool itself, which I really like. So there's MKDocs, which is also a static code generator or documentation generator built on Python. It has a very great extension or it's built. There's something built on MKDocs, which is material for MKDocs, not a theme. So don't get that switched around. It's more like an extension. And it also has all the same properties which Phil mentioned for Vue.js documentation and VuePress. So I think in the end we get to a comparison in the next slide. But looking at the feature side, it's more or less even. There's a bit more of advanced features because MKDocs has been on the market for a long time. But essentially it's actually the same thing. Let's end it with a comparison. So we have VuePress and we have a material for MKDocs. They are both super easy to set up, both based on Markdown, which is easy for product owners and developers to write. It's not that hard to have a structure with that. Plus or minus for us, it was like VuePress, a fairly new player. Phil mentioned Vue2, currently in VTang, has a better search. So there's still a lot of stuff to do until it's that material for MKDocs. So there's a ton of features in the MKDocs that are very powerful search. The only downside, or it's not a real downside, but material has an open source strategy of releasing new features to a payer group, which is the insider version. And after a few contributions or after a few donations, these features go into the open source free version. And the free version is enough for most of the people. So there are some features in the pro or in the insider version, which are nice, but they are not really necessary. So I think you will have a lot more features over VuePress with the free version as well. What we did in the end, we decided for material for MKDocs. Like also like a visual thing, we simply liked that more. There was a dark mode, you know, dark mode, great. Now VuePress has a dark mode as well, but then you get the hang. So actually we started with VuePress and then migrated to MKDocs. The migration took five minutes. So probably migrating back would also be five minutes. You get the tools are very incomparable. I think, Phil, you have five minutes now to tell us something about how we did that on the technical side. The setup in GitHub is quite easy. Yeah. And first of all, you have to do the MKDoc setup. It's just following the instruction. You have only a small configuration file, which you can see on the slide. And the biggest thing in there is simply the navigation. You have to define the navigation there. And serving and building MKDocs is quite easy. This makes really fun because this comment is so short. MKDocs serve is for serving. It's a live feedback thing when you are developing locally or MKDocs build when you generate the pages. And the next thing is directory structure. I think it's a common way to structure the documentation there. You simply have your navigation there and everything you need is written there. The teams have their own space and you can structure it like you want. Yes. And yeah, a nice to know thing is mostly we use draw to draw our conception or concepts and architectures. And we can simply change the directory or the storage from draw to GitLab. And then you save as PNG or SVOG. These both are editable so you don't need two files. And you can simply save it in the docs and it's updated automatically when you change something and save it there. Which is really awesome. That's very awesome. The GitLab repository as a storage is very awesome. You don't have to download it, search it in your local finder and put it in the directory or upload it. Yes. Sometimes there's just not enough features in the documentation tool to generate such a diagram and that's why you need the draw mode. But I think it's okay. You don't want to have that in the documentation tool. It's too hard. Confluence users and no draw already. Yes. And as a setup in the GitLab pages we use for hosting GitLab pages which is really easy to use because we have only a job where we build our application, save it in the directory and push the directory to GitLab pages. This is the whole file, right? That's the whole GitLab. Yeah. This is everything. This is everything. A review app is for previews. Yes. And yeah. We use a custom domain to feel like more inclusive to our technical landscape so we don't have to type in the long GitLab.io page. We simply type in our custom page. So yes. Pretty great, right? What? It's great. It's pretty great. I like the custom domain. Let's show you a quick live demo. So I think we have like one or two minutes left. So let's just do a quick demo and then move to the last slide. Yeah, as you can see here I've prepared something. I prepared a browser and an IDE next to each other. I already did like the MK serve thing here to just serve the documentation. And what you can see here is one of our documentation pages. You can see the nice navigation and stuff. So get into that later. Here, for example, like structuring blocks and admonitions here. And what I can do now is I can, for example, say this is not like, this is like, this is not folded out. It's folded in admonition here, right? So I've changed that. And after a few seconds, it's changed here in the documentation that we do reload. So it actually is live reload, but you have to wait for it for a bit. Like there's a 20 second or 15 seconds delay in there. Yeah, and now you can see this is like folding out and in and not folded out the whole time. We say, I'd like to change it back and want to change the browser version here to something weird. And a few seconds later, the right side is edited. I think you will get the hang of it right here. So it's this again. And what I can do now is if I like this change, I can push it. And so I have a change for you here. I can see what I changed. I can look into the history and see what others changed. You can use the whole good thing, right? So that's pretty great. As a developer, you don't have to leave the IDE. And as a PO, you can use the give that web IDE to edit this. So you don't have to have the live reload, but I think it's good as well. And also PO could use this tool as well. And you've got a markdown preview, which covers the moves. Exactly. So you could also use the markdown preview. Yes, you're right. So you could actually also use the markdown preview, which is even faster, but some of the advanced features are not available there. Thank you, Phil. I forgot about that. Okay, let's move back into the slides. And I think there's nothing much more to say, but thank you very much. For me, it was a pleasure. It was a lot of fun. Yeah, I hope you could take something from that, Phil. What do you have to say? It makes me a lot of fun to do that. And it's a great and documentation makes fun for a long time now. Yeah, I guess so, right? It's fun to do that. I actually liked to write our platform documentation because it was fun. It helped me. I didn't have to think about the layout so much. It looked good very fast. So thank you very much for listening and we are done. Bye-bye. Ciao.