 We have another new tool to consider one. I hadn't heard of until I saw the talk submission. Okay, so I'm looking forward to hearing about it Welcome Alex. Hey All right, hello everyone My name is Alex Akimov. I'm currently leading the documentation team at again. This is a fintech Unicorn in Amsterdam. So I came from Amsterdam yesterday. I really enjoy Brussels here The weather in the morning could be a little bit better probably but yeah, I like to be here and So today I will be talking about our journey how we migrated from a wiki-based System to graph CMS and before I start I would like to ask you if anybody is already familiar with graph CMS If you know about that, please raise your hand. So one two three three and a half three and a half. Okay Yeah, okay, so then I hope that my talk will be insightful and useful for you And anyway, if you have any questions afterwards, you can also ask me if you have time and if you don't have time ask me on Twitter or LinkedIn after that and Before I start talking about Sorry Before I start talking about the graph CMS and our experience with that I Want to focus on one very important idea in this case because Here today we are talking about different tools that we want to use for documentation to create documentation maintain documentation publish test a lot of things like that and when we're looking for these tools when they're trying to Find a perfect tool for us. We are usually thinking about the functionality that we want to have we have our own Requirements we have our processes in mind So we really focus on that part and this way we pick some tools that best fit and then trials to adjust them and customize them at the same time It's important to understand that the tools also Define the way how they will be used within our organization in general because for instance if you use Microsoft Word for maintaining your content It means that all the reviews or the comments probably will be stored within the document in the review mode And if you are using git fostering contents to be a very different cooperation Way to create and maintain Your content and knowledge that you have so this means that it's not only processes that define the tools But also the tools Really have huge effect on the culture how we treat documentation in our organizations Okay, this seems not working and And yeah, this is basically the image illustrating it Then before starting talking about the future With the graph CMS that how we see it in my organization I want to also maybe quickly talk about what we had in the past So when we look at the whole journey about five years ago most of our documentation Was distributed and produced as PDF files and you can imagine that it's difficult to create difficult to maintain Difficult to keep up-to-date Difficult to distribute to all your customers to make sure that they all using the latest version and difficult to analyze difficult to give Get any feedback. So obviously we wanted to Have something more usable more robust and that's how we migrated from PDF files to Confluence which is basically the wiki-based system and Confluence has a variety of plugins. So we were using a lot of plugins on top of that to create an online portal also conference provides us own API and we are trying to Automate a lot of things to generate documentation from source code and we were using doxygen and swagger tools for that and then using Confluence API to generate pages within the documentation portal and we also trying to test a lot of things and it worked pretty nicely But still we had a feeling that not everything Is performing in the best way Because sometimes we came up with a lot of limitations about versioning of your documentation about Making sure that the content that you have is actually what you will be producing because conference is your databases a black box And we were always looking for some ideal tools and ideal solutions for us And if we are thinking about an ideal tool for Managing and creating documentation. I want to ask you once again If you have any ideal tool in mind that you would want to suggest to the audience Okay, okay, so I am really happy that you agree with me because We came to the realization that ideal tool simply doesn't exist because what can be ideal in one situation It's just not ideal in a situation and you constantly seek for something you you constantly try and Want to improve and you think about Different stages of the development of your organization and what I see that for instance the previous setup is Atlassian confluence with Doxigen and swagger tooling was perfectly Working at the previous stage, but now in the current stage of my organization It just simply doesn't work because what's also happening that What I see That our platform is growing multiple times every year Which means that we need to create documentation for that and we are still a very small team of technical writers and we really need to produce a lot of content to be able to update and This means that we want to automate a lot of things just to make sure that we don't spend time on some tedious work And then we just can generate a lot of things we can test all the documentation that we have and Really focus on the writing part making sure that it's clear easy to understand high quality documentation that we produce then growth also means that we need to support multiple versions and It doesn't mean that we need to update our documentation every weekend every day It also means that we need to make sure that we have multiple versions of our documentation available at the same time Because if our developers update our platform every week It means that we also need to have our documentation for the new version available every week But also there are still some customers who are using our documentation For the previous version because they did not switch to this new version and there are still also a lot of customers who are still using this From a version from a month from now from two months from now and we need to fulfill their expectations as well It's really hard to walk in this such agile environment and be able to Create documentation that be usable for every customer Then of course we will focus in on collaboration and easy contribution and reviewing because as I mentioned my team is very small And we really rely on all the knowledge of the people in my organization that can make sure that Every piece of information is valid from the development point of view Make sense from the business point of view and actually provides a lot of value So we really try to involve as much as many people as possible in making sure that our documentation is quite quality then extensibility is also quite important for us because Obviously every tool has its own limits and sometimes it Means that we want to create maybe some nice interaction and user experience on the website Sometimes it means that we want to reuse different pieces of information and just generate it in some specific way Sometimes our product design team can come up with an idea that now these images will work best based on our tests For coral blind people and all these kind of things we need to incorporate in our documentation because the documentation is not Only about the taxes the product from many points of view and then Things like stages deployment and tasting distribution and performance is obviously important with any tool that you will want to use if it comes down to online portal in this case So when we were thinking about all this Obviously there are already Good solutions and nothing is new here So we realize that Some concepts as for instance doctor's code will perfectly match our requirements and It means in general that Documentation is created in the same way and using the same tools as your developers are using then in this case You are becoming closer to your development team Which means shorter cycle in getting changes to your documentation and also developers are more willing to contribute to your Documentation they are more involved in the whole process But also it means that you're probably using markdown or rst files And then store them in a git using git flow in the same way how you developers are using this and Then use something like a static website generator on top of that so there are obviously some pros and cons of having a doctor's code approach in general and What we saw that these doctors code because all the Content is stored in just plain text and markdown files in our case We can easily generate everything we can easily control the quality We can easily test a lot of things because it's no longer black box for you You can get access to it and then you can also create different branches in git and then you can generate everything from this branches You can test so all these kind of things is possible now and versioning is also very easy with git of course it depends on your branching strategy on this kind of things, but I am not going to Focus on this in my talk, but what we also found to be more difficult is that now we are limiting the Collaboration and the way how people within my organization can contribute to our documentation As I mentioned in the beginning it's not only the processes that define tools but also tools define the processes and If we start using something like git and markdown files, this means that everybody who will want to suggest a change to your Content maybe update a code example or something that they need to know about Gits how to make pull requests. They need to make Have basic understanding maybe of the markdown format that you have chosen. They need to be familiar with all these kind of things and In general of course most of the developers if they are already using this stack It's very easy for them and this will also mean that once you start Implementing docs as code you will be mostly receiving feedback from your developers, which is cool But at the same time we will be really missing feedback from a lot of people who are not developers who are working in technical support and helping with implementations They're representing the product side business side and this means that if you are using only this approach Then the quality of the feedback that you will be receiving from other people it will be Very minimal it will be only maybe typos that's in sport or maybe some really small things and We really didn't want want to lose that That's why we started thinking about something that can help us We is actually fulfilling this requirements and also making sure that we are creating something that will be useful for us In the next five years at least and this is how we came up with an idea of having a CMS on top of the Docs as code approach So then it should be a CMS you working with flat files with markdown and RST And this is also not something new. There are already different same as is doing that I think one of the most popular is Netlify CMS maybe there are the same as is I'm not sure about everything and When we looked at them, we decided to pick graph CMS What's good about graph CMS in our case is that? It's open source and for us it was extremely important because we wanted to have a version That we can run in our organization So not a cloud-based version because when you create documentation it can also happen that in this documentation There is something sensitive probably you don't want to expose it up to the moment when it's ready Oh, so you really need to make sure that all the content and the technologies that you're using is still within your Organization and when it's ready then you can publish it Also in this case it was good for us that is based in PHP And it was already familiar stack for in my organization So it for us it was clear how to use it how we can maintain security issues and how we can develop it and how we can Get support from the developers So this is basically the summary from the graph CMS website It's an open source for a file known DB CMS and They also claim they're focused on being crazy fast and easy to learn and use You can test it for yourself if you want But in our experience it was really easy to set up easy to use and it's performing very well on 5000 pages so For us I would say that it was a good choice and What's also important to know from the technology point of view that graph CMS is using? The dynamic site generator when you edit a page at the same time There is another static website generator for graph CMS It's called black hole and it's also in PHP. So you still stay in the same stack if you want to expand it and Use it in your organization Also, of course when we were looking for a solution we were trying to make sure that this is not something that Will just stop its development in a year and for graph CMS what we can see the community is huge and it's really growing I think currently on github. It's about 10 K Favorites for this repository and in general if we look at the commits history at the outstanding tickets We think that the situation is pretty healthy And also if you need some custom integration or some custom implementation You can get support from Trilby media who created the CMS and who can also assist you with Setting it up in your organization and creating different plugins and things for that. That's what we are doing and Now I want to talk a little bit about the implementation that we've gotten the result So here we can see that all the content is stored in markdown files in a github repository, which is internal in our case and then you can edit this content using the UI in a CMS Which is graph CMS in this case or using the IDE if you're a developer and if you prefer to use the same tools that you Would want to use and this means basically that technical writers and Any other people within your organization who want to collaborate on this content can also contribute to that and then From the github repository we can generate the static website using the generator We can test and we run tests against the source markdown files and also against the result to make sure that it's passing our quality and Actually, we also have plans to introduce more tests and LinkedIn That Sven was talking about but this is probably Sometime later this year and this is all internal and external we can distribute the Static website in HTML form and then I'll also use some sort of analytics to see how this content is being used What's also nice that with graph CMS you can create plugins and expand different functionality that you want in our case We created some plugin that allows us to actually see all the reviews and everybody in the Organization can submit a change and they just edit any page that they want to edit or they create create a new page from scratch and Then a technical writer will be able to review and see and then maybe approve or disapprove the change or leave some comments And this is happening not in a git flow. This is happening in the CMS itself Currently we are testing this plugin and I hope that maybe in a month we'll be able to open source it So during this journey we learned some lessons. I also want to share them with you First of all the first lesson mind your stack It means that of course there are different tools different solutions But the solution that you will choose and then it also really depends on the stack That probably you're already using and if you have any developers in your organization who can assist you with improving and expanding this I think this is really important. Of course, it's always nice to learn something new and trendy But sometimes you just need to stick to the choice that You have now and then you will have the power to improve the solution and to expand it and Also another lesson for us is that we can extend markdown when necessary In general especially with graph CMS you have a lot of flexibility. So you can introduce different forms of short course and if you think about Different implementations of the content flow and for instance in your content You want to show some additional info on the site You want to have a block of different steps at the bottom of the page So you want to introduce some structure with which is not natural for markdown files But maybe this is something that you would miss from the semantic Content creation like data it has. So in this case, it's still possible with markdown You just extend it and use something like short quotes Maybe some metadata on top of the page And you just don't need to be afraid of that and don't need to think about your content as friend code all the time only because you Missing this opportunity Then another lesson that we learned that it's always nice if you have a good proof of concept In our case we decided to First change our internal system because we also have our internal system for knowledge sharing and we migrated from two legacy Internal systems to a new one based on graph CMS and on this way We already learned how to use how to set it up how to test it and based on this experience It was really easy for us to implement the same process for migrating our external documentation Then another of course lesson that in this case we did not set it up from the ground so it was already a system and With our public documentation and we also need to maintain and update it every day. So it means that we cannot just Take our content and then spend a week to move it to a new system and don't receive any updates during this week So in this case When you're doing the migration it means that you will be repeating this process Many times and if in this process there are some manual steps when sometimes you need to copy files from one folder to another Or sometimes you need to ask another guy to run another script or things like that. It never works perfectly So if you're in a similar situation as we were I would just recommend you try to automate every step So it should be on a single button you do this you get results and you test the outcome and For us it was also difficult because we were migrating from Confluence using Confluence API and with some Pandoc on top of that and some other scripts So automation here really helped a lot Another very interesting realization is that problems during migration can be fixed at different levels because in our situation when we try to migrate first we saw that the outcome is really complicated and has so many errors and we were trying to improve our migration tool to write more complex scenarios to catch all the edge cases and At some moment we just decided that it's also possible to change the content that we currently have in our case In another system and because technical writers and developers are sitting in the same room and they can just discuss it quickly and Solve this on the daily basis every time we see a problem. We can make a decision. Do we need to write some specific code to? Actually solve this case or do we want to fix it in the first place because then it doesn't have a lot of value in the content that we had in the original system Six lesson is that it's always interesting to learn from users and in this case We also organize some user testing with our internal user just to see how they contribute and this was Extremely powerful because we found out that we were expecting them to click on some certain buttons And then some certain label just didn't work because nobody was able to understand this except for technical writers And then after such user tests we just improved the UI and changed a lot of things and now it works best for technical writers and for everybody who can contribute to us and Last lesson is that everything that we do we are also trying to Contribute to the public repository and just open source And this is of course to make sure that the platform that we have chosen just in a good shape and that we can also support its growth But also for us It's just easier to reduce the maintenance costs in the future because if you want to update a new version And we have a lot of custom code written for us And we need to measure somehow and in this case we just don't need it because it's already open source is part of the system So I think I hope it was useful for you And if you're in a similar situation as We were some time ago. Also, you can reach out to me and ask any questions or we have some time to Discuss some things now as well Yeah So in our case all the content that we distribute is a part of the development portal and if a developer at something then we can also just See it in our lock of changes and then we can review it and then yeah, I'd basically See if it's following our style guide and if it's compliant Then we can just publish it as a part of that if it's not then we can discuss with the developer where we want to see this content Yeah, that's a good question For me it's still interesting In all these phases, but I would say that in the editing process as well and its editor It's still probably not that rich as Microsoft or something like that But maybe sometimes you just don't need it and we are also trying to improve it to fit our needs But it already has a lot of features. So I would recommend to look at this That's a very good question So everything is possible for us currently we are not receiving a lot of requests to do this so then if we See that it's still required then we will need to come up with a solution how to generate it from markdown files I hope that it's still possible for instance in my organization We also create point-of-sale terminals which are distributed in boxes and with these boxes probably it makes sense to have some printed documentation Currently just all custom made but because also it's something like in IKEA You need to have good images and it's not so much about writing. It's also about the way how you present and tell the story Any more questions? Thank you very much