 There we go. All right. Welcome to the event. Thank you very much. Oh, yeah. Thank you. Hi, everyone. Nice that you are here. First disclaimer, I've not used this anymore to work with Max, so maybe I messed something up because it's confusing how Max is working. But let's start. I will basically run for the first couple of flights because I only have 25 minutes, so I have to make it a bit quick. So let's talk about automated testing of documentation. Actually, the first question, how is actually as already in their workflow for documentation like CI setup included or is using CI CD for testing and deploying not only the product but also the documentation that runs something like simple or not so simple quality insurance tests of your documentation in CI? No one. Oh, okay. Cool. I mean, it's not hard. It's like running CI for your normal things. And let's just jump straight into it. Well, it's the first part. It's the boring part. It's about me. I'm a doc ops engineer and work for PonoVix. I have old school student deaf ops slash SIE background. I'm also involved in some open source thingies or communities like Plone. Maybe some people here in the room know it. It's CMS or Enterprise CMS based on Python. And also involved in two other communities like TestDocs and WriteDocs. And I really like to complain and this talk is also quite affiliated and basically based on experience from various open source communities so that may or may not fit the use case if we are working on a company. So first we're already checked. We all know that, so we learned in the meantime, writing is not that hard. Sometimes we all just write a couple of lines of documentation, but no, it's not because you want to make sure that you reach the audience at the audience understanding your docs and stuff like that. The same with continuous integration. Basic stuff, at least if you're experienced with continuous integration or a developer, it's easy. But if you're starting to build up your CI system and you're getting more tests into it, it can get quite complicated. And also, like always, there's no perfect solution or no good solution. Like always, there are lots of different ways to reach your goal. It always depends on your effort, time, money and what you need. And also, automated tests are nice, but they don't can fix all your issues or problem. It's only one part which can help you to make your life a bit easier. Basically, all the things like what insurance start in your editor and after your editor with people like real humans who are trying to read, understand and test your documentation. And then this claim again, it's based on open source experience and some of you may or may not recognize some comments to some repositories. And that's John Binderitz. So, I mean, we're in 2019, but actually I'm praying this tends to a couple of years. Documentation these days is an important part of your product. Just push your product out and say people try and install it will not help you. You will not sell that because you get annoyed or your customers get annoyed and move away and also it will cost you lots of money because you have to spend lots of money and effort and time and head desk or other annoying things. And also if you want to have new developers able to jump in quickly provide them with usable documentation. It's really perfect for onboarding because in the whole onboarding process they can also contest basically the documentation. And like always, I like to say if you have no docs your whole product is basically broken. Yes, and also the other thing it's important to take people tend to forget that with writing documentations. Take care about the editors, meaning the people who basically add to your documentation. So that is really my message to all your awesome developers. It's really nice that you're trying documentation but also try to write meaningful documentation and readable documentation. And this was an example, a really quick example. This is a code of conduct from the awesome write docs community which is awesome and they are really nice people. And this is the source, it's a restricted text. It looks awesome right now at HTML but at the source it... Well, I think there's some room for improvements because personally, it's my personal opinion, reading that and editing that for me it's way harder than doing that which is exactly the same file but then following a markdown style guide into some couple of tiny warding style guides. It's really the same but it follows the whole F shape how people tend to read source code or basically sites or newspapers and also it's certain line length and other stuff so it makes for me at least easier to work on stuff like that. And then, well, now we're getting to the fun part with whether it's checks or quality insurance. The most important thing is you need the plan, you need the ideas. You have to know actually what is your goal, what you want to reach with checking documentation. Lots of people say, oh yeah, let's do it, cool. We start checking it but they have no idea what kind of checks you want to have. So first you have to define a goal. Is my goal just I want to remove all the typos or if my goal I want to have a certain level of readability. So this is really important and also use same values of your checks. Don't start with two strict checks. If you start with two strict checks all the people who contributed to your docs will be really, really unhappy because basically your tests or your CI in this case will scream every 20 seconds against you and it's nice for later but if you want to have nice results and people are motivated start slow and tweak and tune them later. Also it's important, if it's possible start from the beginning of the projects also with checks of documentation because if we have already something like, I don't know, 500 sites of documentation about the user manual and adding then checks and trying to fix all that it's possible but it's not the nicest thing to do. Then also important, be strict but leave friendly so give people if the test is failing meaningful message why it's failing explain why it's failing and send them both links to background information how they can fix it. Same as for error messages and also important know your audience who's contributing to the documentation that maybe if you work in a company easier because you have a writing team but if you're involved in open source project sometimes really first have to know who's contributing the most because depending on that you may want to adjust your checks to make them at certain levels more user friendly or less strict and there are lots of different ways how to get information I like to use Grafana hooked up to my Github or Bitpocket repository to give me information about my contributors pull requests, who's doing pull requests who's doing much request and all the other stuff also use analytics like more good analytics whatever you use to get information about who's with it on your site how they're coming to the site how they're looking up content on your site how they're searching for your site because it also gives you an idea where it's important to start fixing up your documentation basically so maybe it's a more important first to run checks only on a certain part of the documentation and later extend then then writing on all of it and then really really important since we're also talking in CI CD developers are your friend be friendly to them work together with them it doesn't help if you just stand with your foot on the ground and say I want to have it like this try to adopt the tools that they are using try to provide them with meaningful templates and also make it easy for them for PloN for example we created Mavin which is our friendly helping robot which is really nice because if people starting to write PloN trainings or other parts of the documentation it will create your boilerplates with the title the last the write RST syntax configure checks and stuff like that and this is nice because first is CLI and our developer they like CLI but also it gives them a nice starting base to start from and move on also if you run checks first we did run checks on the whole documentation which we'll also see later this is nice but to make the checks fast and quick just run the checks on files which are changed you don't have to check 500 pages when only one page is changed then a friendly reminder like you should know that of course protect your branches if you don't protect your branches you may end up with weird commits to weird branches which will result in weird documentation online if you write checks use the best coding practice against the languages you write them in and also make sure they are passing tests of the language like I already said keep checks easy start small and make checks depend on each other so just run the you run an html deploy make sure that you only want to deploy if all other tests before that are passing otherwise you will end up deploying broken html and like dog said code you see a smaller example do not break the bolt if you break the bolt of course fix it I have to move up a bit and now it's demo time which will hopefully work first a really short disclaimer the demo setup is also online later this is only for local usage don't try that on your production setup because I do evil stuff like mounting docker socks and volumes and doing that it's fine on a laptop but on production machines you use kubernetes t308 or install it up bare bone and basically we have two short demos one which we use in Travis hopefully the internet will work and the other one it's running and this is for later and how to get my do you want a do you want a mirror because there's a very nice shortcut where's my mirror below this is basically what is running on Travis and then deploy deploy to natively and if you check at the moment it will tell you that well it will tell you that basically it's failing and because of that we can't deploy to our website and basically it is failing because we have this one line line 25 down there so basically it's a minimal inter with checking your writing guides and we have another style guide that we don't want to start lines or sentences with there is and because of that it's failing and if you move it now I love it yeah I know I know I know that's also the internet ok for the others test then blah blah blah history come on slow internet then we see it basically it's running and now in the meantime we have locally also set up with the drone and a guitar and here's a basically a repository and we also see that lovely it's a bit of why is it so small so now we can see that the built is is basically failing and this on purpose we are using basically the same checks which we are using on Travis but then with the stricter settings and I tend to do that that need because I personally I run stricter checks for myself locally on CI I always have a CI locally running and if they are passing I know for sure that they are also passing on the main site and the reason why I use stricter checks for myself is to really really make sure that we slowly basically improve the quality of the docs and we can also now just try that let this then here and I mean this one will still fail because I will not fix it now and now we see it's it's running and the link is it's okay hopefully when we have internet the internet is really fun here this now if you can see for natively past it's green and it's deployed to the site hopefully yes for the demo I'm running just the basic link checks and then a style check with Valerlind which is checking for for spell checks language that I don't use certain words that I make sure I don't start sentences with various so or but certain line length paragraph length and check terms and that is it basically but there is no the possibilities are endless for example with Chris the veil setup you can do really funny and insane things the fun part the dangerous part because you really from what I want to test because you can go really really crazy and test lots and lots and lots of stuff but you really have to ask yourself at least when you start from is that really the goal from the beginning maybe sure over a certain amount of time I want to test all the stuff but I want to test maybe wanted to start small and also the important thing is to check you can check the levels of testing like is my test giving me a warning or a suggestion or it's falling so I for example start basically to set everyone to suggestion and basically the test is running through but it's telling me from hey maybe you want to change that word or your line is 20 charts too long or other stuff and then later on step by step or run by run I adjust them and move them from suggestion to error or to warning and with then you also can define levels with with errors the builders failing and they will not deploy with warning you can also I can configure and you can too like like the spell check if I get the warning with spell check then fail but if I get the warning with my line is 20 charts too long then run through it and then you get the whole matrix of different tests and with the different tests later on you can adjust them and that helps you to improve your quality of your dogs slowly and you don't have to run like me locally you can also use githooks or or other stuff and yeah this site is deployed lovely lovely lovely and this one is of course not having internet but it it's the same check and if you go now back to the slides that was a bad lead or thank you to provenics because they are awesome people and actually the writing and project team because they keep up with my ideas that's not always that easy I think and thank you all of I want to apologize because it was a bit short and a bit really really short but it's 25 minutes it's really hard to tell all the stuff in 25 minutes that bug is a question imagine that it would be good to first start with simple rules and then tune them what would happen with documentation which was written without those new rules we did for example with Ploem the same because we had lots of documentation there were no rules and though we started to write a whole cheat about where we want to be in the future and then we took that apart and said ok this is the end goal but now we have to repeat the part in smaller steps and first through reaching all the smaller steps step by step we reached the end goal no that is why yes and no if you run them on all the existing documentation yes but how we solving it now is we run it only on the fights which people are including their comics so I have maybe all the 5 minute pages but since there was only a change on one side only the one side is checked and you only get the results for the one side the other 499 side they are still bad and not improved but by this we are improving the documentation over the time yes it's possible there is this one guy from Amsterdam also talk at the last year he is doing that for things basically he wrote a plugin to do that and there are also some experiments with having all your code example in your repository and test them then only in this repository and then include them from this repository or code example repository into your documentation there are different ways how to do that all of them are still kind of buggy and not working perfect and we also still for Plone figure out which is the best approach for us because it should be an easy easyish maintainable but still also giving you basically results so if you use like for your hosting your documentation something like Aspidog and Antora then it's basically easier because they can fetch different repositories and combine them into one nicely run HTML output thank you very much