How we use "Docs As Code" to engineer stunning Documentation for Plone 6 and friends
CC Attribution 3.0 Germany:
You are free to use, adapt and copy, distribute and transmit the work or content in adapted or unchanged form for any legal purpose as long as the work is attributed to the author in the manner specified by the author or licensor.
Strack, Sven
Building, maintaining and continually improving documentation by doing Docs As Code the DocOps way. In this talk we will share our journey from our current (Plone 5) documentation to modern and astonishing docs for Plone 6 and related (JavaScript) friends. We'll talk about the reasons, how and why we made certain decisions. Besides that we'll discover how Googles Summer of Docs helped us, and we'll see where we are with the quality and setup of our documentation compared to other open source communities.
 Hello everyone, how are we doing? Okay, let's get started. Wait, how do I get started? Oh, it's not turning. How is it? How I switch these slides? Oh, look at this. Okay, first of all, shout out to Red Turtle. First of all, thank you for the huge tray of tiramisu. It's awesome, and we will try our best to enjoy every bite of it, and thinking about Red Turtle and Plone. We will do, we will do. So welcome everyone, let us say it. And first of all, thank you for attending my talk, and also thank you to the community to accepting this talk proposal, and also thank you to the community and to Red Turtle to make it possible that I'm here, because that was not that easy. So let's move on. Okay, first it is a disclaimer. Basically, this talk is only about the CoreDocs, Volto and Kiewitina. There's nothing about the training documentation or add-ons documentation, because these are completely different topics, and because of that they are not part of this talk. Also, everything like what we are telling, or what I tell in the name of the docs team, is not written and stoned yet. It is basically what we discussed, and we think it's the way to go, and lots of the stuff, so techniques, they are also used already since a couple of months in production, even for some huge companies like certain banks or insurance companies, and the stuff is working, but then again, I mean, that is what we came with up, that doesn't mean it has to be completely like this. So first, let's get into each other. Who is developer? Wow, who is technical writer? Who is a developer who is also forced to write the documentation? And who of you love that, the drawing writing documentation? This is less. And who is already familiar with DocSys code and using the approach like DocSys code for intensive testing of the quality of your documentation? Wow, some already, that's cool. So there are a gender of today. Can I make that bigger? Anyway, I look there. So first, we have a short look about the current status of our documentation. Second one, we will mention shortly about the Google season of the docs. Next part, then we will talk about some mistakes and it's time to lower the barrier for our documentation because we have some slightly issues there. Then we move on to the really cool part, which is where they live the future, what I call Plone X at the moment, because according to Iriku, I'm not allowed to say Plone 6 anymore. And this also will cover then the last part, which is 5, which is basically covering the whole DocSys code approach and why we should use it and why it's helpful. So let's start with the current status of our documentation, how we are doing. And the next quote on the slide, just to make it clear, it's not from me, that is from one other member. So our docs are far from perfect, but considering that there are only less than a handful of people working constantly on the documentation and all of that is basically done as volunteer in free time, there is no company behind it or no one is paying for it, we are doing not that bad. And I think that is a really important thing to say, because it's like this. People in the audience will know me a bit longer, they also know that I love complaining about lots of stuff, including documentation and how bad our documentation is. That's completely true and I still have this opinion, but then again I also grow a bit and I mean, we have no company behind it, taking that we are doing it now free time, for that we are not doing that bad. So that is what we currently have, as you know it and you love it or you hate it and you love and hate relationship with that. And there are some things that are not really good or where we have room for improvement. I mean, when we came up with the structure and all that, it's partly because we didn't know better how to do it, because when we started to do the documentation we had no clue about documentation at all because all of us were basically developers. But we are facing currently some issues with the setup, starting from that the structure is not really clear and confusing. We have the weird mix of user documentation and developer documentation. The documentation in general is written way too focused on developers, which is not surprising because 90% of the stuff is written by developers. We never ever thought about a content strategy or a message strategy, the only thing what we did in the beginning was thinking about what's more or less a okay kind of structure for the documentation. But it was also then again years ago and like, the plan changed and also how we use it changed. So it's not perfect. Personally, I say it's bad use, but I mean it's not bad at all for a volunteer project. So let's talk shortly about campaign points besides them which I already mentioned. Like, we have no content architecture or strategy or message or something. It's confusing, it's too developer focused. We have lots of stuff which is redundant, outdated, and it's not available or not matching up at all. Like for example, using, we have, and still in the Plone 5 docs, lots of references from Plone 3 which are never got updated. If you're talking about the editorial or markup styles and quality, it's inconsistent, it's completely confusing, it's way too wordy, and lots of other things what you could improve. And then also not forgetting like the whole build and deploy process. It's super unstable, it's slow, it's really, really complicated at the moment, and also it's not that well documented. So I mean the people who are doing it, like it's usually Paul or me usually, we usually are able to do that, but even I for example getting annoyed because I never ever bothered to write documentation about that or at least not proper documentation. So we sort of fixed that. So for that I'm really, really sorry because in some of those parts I was at least involved in writing it or in making decisions about it, like the current state of Papyrus, our deployment tool, or other things. But it's also good because now it's time to move on and change. So you also maybe mentioned or recognized in the last year there was a list going on in documentation on the less frequent releases of New Dogs. And this is basically because we split more or less the documentation team. So basically we have one sub part which is the current documentation like for Plone 5x something. This is basically at the moment maintaining the build-up to infrastructure, maintaining to the dogs and improving the dogs, but it's also getting slow because we are also depending there like always on other people and developers. And from the co-op dogs team basically Paul is doing the maintaining and building. And I switched more over to like Plone X or Plone 6. This is like the whole preparation and thinking about structure and building the new setup which is including editorial style guides, markup style guides, working together with the Volto team and even with the guillotine people to thinking about new content architecture, what kind of message you want to do, user stories, new build and deployment infrastructure to make it flawless and faster. And then also like you see on the bottom there's also Google season of dogs because we all started, Google got granted to the Google season of the dogs so we are working together with our technical writer Chris and also then with Kim, Victor and lots of other Plone people to improving the developer or the experience for starting developers for the Volto dogs and that was also including lots of talking about content strategy, message strategy, architecture, what kind of dogs make sense and so on. And this is basically the Google season of dogs which is still going on. We are now basically at I think halfway with the whole timing so soon there will be the first commits with the new blueprint about the new structure about the developer dogs for Volto. And this is really important. We should lower in the future dogs the barrier for contributing to documentation because nothing is more demotivating and annoying if you, for example, you are browsing the dogs, you are sporting a typo or a grammar thing or some just wrong or outdated documentation and you only want to basically add two or three lines. Basically you want to create a pull request where you just say I changed line number five because it was outdated, here's the new write version, you want to create a pull request and then you want to see it somehow, somewhere end up online in the documentation. Currently that is not, that is the end possible. Currently the whole thing is kind of complicated and really annoying because we don't have, like, for the average user an easy way to refute the dogs easily to getting the research out faster and things like that. So that makes it less fun to contribute. The really important takeaway here is we should make it as easy and as effortless as possible to creating pull requests with improvements to documentation and seeing them as fast as possible online because that basically creates good feelings and makes people happy and also motivates them to create more. But this is also really important, like, I'm going to come. So you always should remember, usually you're not writing the documentation only for yourself, there's also an audience. So that meaning if you write documentation, never assume that the people who are reading documentation have your knowledge about certain things that you are writing. Maybe you are working since 10 years on that and the person is the first time ever reading your documentation. Also always try to provide background innovation, like, for example, Whiskey. Different information about Whiskey and maybe a link to Whiskey or to the Whiskey documentation with blown, edit, not only say use Whiskey, people will stop reading it, stop continuing because it's just demotivating and also really unfriendly and hostile. Be always clear. Try to be, like, as short, straight to the point, friendly and clear as possible about what you are writing. We don't need sentences from, like, 20-something words. Just make it short, make it easy, because also think about translation and accessibility. And then also be consistent. We still have a huge problem in the blown documentation that we use, like, for the same functionality, different terms. And this is super confusing for people. It's the same, like, if people, like, for example, using, talking more like developer language, we have the standard default Docker container for blown and we have the volatile Docker container for blown done by KitConcept, but they are not, like, identical. They are built different, so people are getting confused, because if you look at the source, it's just different. So be consistent. And also, like, we always, we as community, alter the documentation, we should try to be more friendly and welcoming. We still have this issue that we always tend to write, everything is just easy and just do that and things like that. All the stuff is not easy. Even, I mean, if you're a developer and you try to write proper documentation, you will also find out writing properly and good documentation is not that easy. So, and now, move on to the fun part to the future. Now that was just ranting about the old setup, and now let's have some fun about the new stuff. Are you already asleep or are you still awake and following me? Okay, cool. So, like, in the title description of the talk, I mentioned stunning, so first, maybe I thought I should explain what I mean with stunning. But stunning for me, it should be always about all aspects of API, or in this case, API-related documentation. That means, first of all, it should be appealing for your eyes. If I look at it, I should be motivated to look at it, because it should look nice. I don't want to look at an interface from the 80s, or which is completely confusing because there's way too many information. I also would like to have some pictures and graphs, because they make it easier to understand stuff. I want to have a clear content structure that is completely clear to me, where I can find stuff, not mixing developer and user interface documentation and other stuff. I want to have clarity, like what I mentioned already before, be clear about your wording, be clear about your grammar. Also really important is good SEO, so think about how you write, what you write. Because zero is not only good because you're ranking high in Google and people finding you better, SEO is also good because it helps you to get a better clear picture about your documentation at all. And the other thing, be accessible. We have still kind of issues with accessibility. We should care about that. Our themes are working with green readers. They are working for colorblind people. Another famous thing, people tend to have lovely sentences in your documentation, like, click here for more information. And I'm really sorry, this is just wrong. Stop using click here for more information. Use a description that people understand if they click on these certain links where they end up, because this is how screen readers are, for example, working. Also use this, like as link descriptions in your source code of your HTML link. I mean, come on, we have to talk 19 almost, so we should do that. So in one part it's like moving on to Docs as code, and this is now a lot of text. So what Docs as code basically means is it assumes that you use the same tooling for writing documentation, which you also use for working on your code. In the same manner you write on work on your code, like, for example, using plugins and linters for reporting style violations or errors and other things, you should do the same for documentation where you check, like with linters, your documentation against your editorial style guides or your markdown RST style guides and other style guides. And then depending, of course, on documentation, you always should add some more tests for the consistency of your quality. That means, for example, if you decide to write your Docs in US English, check your documentation that you're really using US English or not mixing US English with UK English, your links are working and things like that. And why should we use it? Because if we have consistent documentation, it helps not only the users because they're happy, it also helps the developer, they're happy because all of us are finding stuff faster, which also could lead to that we are able to do faster releases. Also really important, consistency and good documentation creates some kind of trust with the audience, with the user guy, with the people who are using it. If people are re-genizing things because, like, think like what we did with README, when the Docs team introduced a couple of years ago the example, default README, they were also some resistance and people were complaining, I want to still use my hitchhiker to Galaxy README and other things. And these are nice for your private or maybe even for collective stuff, but think the bigger picture. Like, if you are, for example, a CTU and you browse the plough and organization on GitHub and then you figure out that README is always written in the same style, that the documentation is always using the same wording and the same terms, it actually creates for me a warm feeling and I started to trust this organization and these people more because they see that they put effort into it and they try to make it good. And also take this and think for the bigger picture. This also is really good for you as a plough provider or a company because then people look up which companies are involved in contributions to plough and selling plough and then they also see that you are taking care of documentation and this is also good for marketing. Even if you don't like it, it is marketing. And at the bottom, for example, there is an example picture of running like Docs as code, as a lintar testing that I don't use here as a link description and that the second test is that I don't start paragraphs with the words but and this is just a slight example, they are endless tests what we can do. And to make it easier because it was always now a bit technical and just too many words, here is the theme and like as a graph, basically the idea is you start writing in your text editor and you review by yourself, then you commit to your version control system, then there are already some checks running, then you may create a pull request, then CI CD is running against some QHX and if that is nice and everything gets merged, then the deploy is triggered and the new version will end up somewhere online. And this is even more because we are not only building cool automatic deploy things to websites, it is also like we are working on tools to improving the whole experience, like how to work on documentation. And this is for example, this is an add-on we wrote for VS Code. Basically, it is an extension pack for VS Code which basically installs, I think, 10 different add-ons for VS Code which are pre-configured for writing documentation according to best practices. And if you are already, for example, using VS Code, you can also say, I don't want to have automatically installed in other extensions, then you can get a link to the detailed documentation and just can decide and do it manually, copy and paste. And this is also really important because this is where docs are at least for me at starting. It is not just about this last cool thing with CI CD and deployment, it starts in locally in your editor and using also linting and tooling in your local editor and on your laptop. And this is then, for example, how it looks like. This is an example taken in order for real life. This is basically like an API of a well-known Dutch bank. And the technical writers of these banks are using exactly this VS Code setup. As you can see on the left, there's a markdown spec which they're writing. On the right, they see your output HTML and on the bottom there, like you know it from your Python linters or other linters, you get the whole output about what is according to the defined checks, wrong and what you should improve. And this is basically the same, the same tests as BB8. BB8 is my personal helping droids which is basically if I do a good commit, running all these tests automatically like in containers on my laptop, and it's checking for markdown, then it's checking for accessibility, it's checking my open API spec, it's checking for broken links, it's checking for my other style guides, then it's checking out with Lighthouse for accessibility tooling, and that takes some time, so be finished. And then basically if everything is green, BB8 will automatically stage my commits at the commit message, and then I still have to push it to my repository. And let's jump a bit more into the details and change, but everything will, all of them will change. The biggest change, the core docs will move from restructured text to markdown. So who loves it, who hates it? So there are a couple of reasons why we make the decisions, and we took a long time to think about it with lots of pros and cons. So, Spring's and restructured text are not bad, they are working, they are nice, but the core docs, and I'm really talking about the core docs, Volto and Guillotine, I'm not talking about add-ons or other things, we use less Python than we used years ago, we are moving to more different things like using auto-reacts, using other JavaScript things, using API things, so we also should adjust our documentation tooling for that. We are also saying we do that because we also want to attract more people, it does not make sense for us because we are a small and even shrinking community sometimes, to force for example React developers to write restructured text. They are no markdown because they are used to markdown, it's way easier for them to write markdown, the same goes basically for open API specifications and swagger and all the other things. So we should adapt and make it more friendly there. Also 99% of the features which are built in Spring's we are never used, they are awesome and they are nice but we don't use them. So why make our life complicated and stick with that? We will use Common Mark as spec for our markdown, because lots of people were always complaining the big advantage to compare restructured text with markdown, besides that we are able to do more things with RST if there is an official spec for RST. That is kind of true but not really anymore because Common Mark is getting to be the official spec for markdown. The whole board from Common Mark is quite active and also the specs which they came up with, they are really really nice. So for us that's also important, they are more than enough. It's covering all our use cases and yeah, for that is perfect. So the other thing, I mentioned that we are stuck using Spring's, we will move to Gatsby for building and deploying the documentation and there are also different reasons why we decided on that. First of all that is also what WOT was using, what lots of other React projects are using. Because we suffer now, for example, really hard from that, that we are not able to do proper Spring's changes and buildups, because there are not enough people who have time or their energy to do it. With Gatsby we can get more people jumping and it's also some technique that they know and what they love. And there are also lots of add-ons and libraries already there anyway, so it's easier to get changes and we are more flexible. And also this is really important, there are more people able to maintain the stuff. It's not basically the bottleneck, it's not Paul or me or two other people on a Spring's, then basically it's really the responsible from the whole community. We get a new build CLI. Some of you may already know that at the moment we are using Papyrus, which was something what we set up a couple of years ago, and then it changed into some Frankenstein set up with lots of different Python and bash scripting and weird configuration files. It's complicated, let's keep it by that. And this is now for example interesting because there is no decision made. So basically I tried out or I'm still playing with one JavaScript based one, where I use Oaklyph which is from Sageforce.heruco, and the other one basically it's Golang based. And they are pros and cons to both of them. And like if you use the JavaScript base, there are more people from what's a 100 JavaScript who can help do it, so it's easier to contribute because more people know JavaScript or note in this case, but the less cool thing is they are less native integrations to like for example container APIs for Docker, for Kubernetes, for Firecracker and things like that. I personally I would go with Gol because I got all this native API integrations and for me personally it's easier, but then again it should not be only about me and what I like or prefer, sadly, sadly. And this is also about now why I'm basically asking like the community, maybe the decision. If people are saying we are helping and we know JavaScript and we willing to help, it's fine, I'm completely cool for that and then we go for it. But if just like sadly quite often people are only complaining but not jumping and helping, then I will just go with go and you have to live with it. I'm really sorry. And the reason why we did not choose Python, it's quite basic. Python is nice, but still to today I'm not able to get native binaries from Python. To run a Python binary you still need to have Python installed on your machine. And the idea is I want to have it as easy and as for less for other people. You don't have to have something like Python, virtual and for other things installed on your machine. Just download the binary of CCLI and you can run, deploy and be happy with whatever you like to do with it or what you can do with it. The other thing, we will start hosting on Netifly. That's nice because it's fast. We're getting automatically CDN and we have one less server to maintain ourselves. And the really, really cool feature is we get preview of branches. That means if you create a branch of your documentation and you write stuff and then you push the branch to GitHub, you automatically get in GitHub and URL which is pointing to Netifly where you can go and then you see there are compiled run on the HTML of documentation of your own branch. With those are CLI and the setup of the editor, like VS Code in this case, you can still do it locally also. But this also makes it easier because maybe you're not using VS Code, you're using, I don't know, Nano or Joe or some other weird editor and it's not configured yet. So it doesn't matter, write in it, push the branch, go to Netifly, preview your branch there. If the branch gets merged, then the preview branch gets automatically deleted, so that's also cool. And it makes it also easier if you want to ask other people to review it, so it's less work and it's faster. And this is basically how it will look like in GitHub, it's saying the preview deploy is ready and then you can click on it and then you're ending up on your branch. We will move to GitHub action for continuous integration. The nice thing is all the checks we're using, they are container based, so you also can use them with your Jenkins, drone CI, build kite, AWS pipeline, whatever continuous integration you prefer to use. But for the docs self, use GitHub actions because they are fast and working for us. And this is for example, like the debug output of a GitHub action which is running a link check. At the bottom, you can see it is red, that's saying it fails because I wrote a poll on wrong, I wrote it with two ease. What we also do with CI CD, to make it clear, it will not be only link check, we will run currently something like 20 different checks for markdown quality and the quality of the content. And we also use it to run lighthouse checks once a week at the moment on your site. And there's no decision made how we configured, like if the docs team gets a mail with a link to download the latest results or something. But this is really nice because it gives us more insights about the performance of the site, accessibility, CO and stuff. So if we do that over a long time, we can see how we are increasing or decreasing and it's nice to get a better overview. And also one reason why there were less contributions to the documentation is because we are writing on a completely new blown documentation guide. The idea is that it's one guide to rule them all. This is a completely markdown style guide and a total style guide about wording, terms, length of sentences, lines, why you shouldn't use certain words and stuff like that. It is almost finished. I think we are now at 99% or 98%. So there are still two or three tests for the style guide itself, something missing. It's good to go. It's also nice. This style guide got a review by technical writers from other companies. For example, we got a review from Sarah Maddox from the tech team from Google and from another person from the Microsoft Azure docs team. And they loved it. I mean, still it's not perfect, of course, but the feedback was really, really positive and they even took some parts of them over to their own style guide to be sure it was Kubernetes to be clear. And also what we will do, we will do content splitting. At the moment we have just Docs.plonar.com. There you have developer documentations and user documentations. And like I already mentioned, this is just kind of confusing and not clear from the content structure. So we will split that in Docs.plonar, which will be end user documentation for Volto and end user documentation for our current front end. Like if you want to create a site, click here, create a site, blah, blah, blah, blah, blah, how you set, do the configuration. All the developer documentation, meaning REST API, development add-ons, theming, Volto, back end, Guillotine, will go to developer.plonar.com. This is nice because there's also a common setup and standard for lots of other projects, open source or commercial using it. People know that, they know what to expect. And this is also why we decided because it also makes it easier and faster to add changes and deploy stuff. And another fun picture at the bottom is the same link check, but then he's passing for a Plon document, but this is running on a drone CI. And shortly about content structure, these are only just some mockups. What I created, I am really bad with creating mockups, but it doesn't mean that it will look up in the end, look like this, just to get some kind of idea. Basically, the idea is, for example, if you go to developer documentation, you get clearly like the topics. I want to have Volto, REST API, Guillotine, or maybe developing Plon Core or whatever we add there. And then, for example, you click here on Volto and then you get a really clear page, not too much stuff around, not too much colors. I mean, we should add some colors, but make it clear that the content is important. It's not about colors and fancy pictures all the time or gifts or whatever. The content is the main message what we want to divide. We can still have posts about Brittany, docs, and other things and lots of glitter, but we have to find a way to do that properly. And because of that, we're also getting a more flat structure, which is nice because we're getting shorter domains. So, for example, docs, Plonork, external, Plonup, Dexterity, docs, advanced, validators, which is really a mouthful word change to develop other Plonork Dexterity validators. This is easier for people to remember. It's better for CO, and it makes me a lot more happy. And also, we will start running like, and at the bottom, you will see this basically, a standard test using Spectral against my Open API spec. We will also start using that for Plonrest API and for Glutina, but not as part of the docs team. And in case people do not know me, that is basically, that is me, talking about fancy job descriptions. My officially job description at the moment is content architect slash docops engineer. And basically what I'm doing is I'm working on API and API-related documentation for high availability. I hate this word. API is gateways. Think about APG or MuleSoft, and then you're talking with banks or insurance companies, and you have millions of requests per second. And that was all. So who is completely scared? Who hates it? Who is not agreeing with everything? Scared is okay. Yes. We have time for questions. As ever, I will ask you to indeed ask questions and not give a monologue, because that way, if you want to hold a monologue, there's lightning talks. And wait for the microphone because it needs to be on tape. Or how do you call it in the digital age? Hi, thanks. I know you just said that images and glitches are not everything, but in good documentation, we do tend to add screenshots and pictures. Oh, sure. Sorry, I didn't mean that. I know. But how easy is that in the new documentation system to add? Way easier than current, because we are using, I forgot the slide about that. We will use Puppeteer for that. And writing things for Puppeteer, you can choose if you want to do it from a command line, or if you want to do it via an editor, for example, in a web-based editor, if I'm right. Yes. We're using Puppeteer, which is well maintained, but there's also a very nice editor that does clickity-clickity. Basically, you click your text together, and then it spits that out as a command line file. So even I can create a test just by clicking. And then I say download this as an XML file, and it will repeat itself for automated screenshots. And these things are run as also as GitHub action once a week at the moment, then as Chrome, and then we embed the pictures to the right places. The base idea is still the same, what we're doing with the robot test at the moment. It's just easier, because you can choose to use an editor, or like me, just do it from command line. But it's more stable and faster than robot tests, for this case at least. Sven, one question. You're switching from RST to command mark, from Sphinx to some other systems around, and did you have something like a preview for us? How it looks like to write just the normal documentation, how to link in between pages to get... Yeah, well, all the stuff we have with Sphinx at the moment, where you can include code, highlight the stuff you need and everything. This is partly already covered in the Star Guide, and for the rest we will publish it at the moment when we really go online with it. But the idea is basically it's working like normal markdown things, that means as we're right, there's a bit less functionality than what you get with Sphinx out of the box. But after comparing all the pros and cons, we decided it's worth, because adding links in markdown is usually, at least if you use a pre-configured editor, or even if you do it from hand, easy and fast, and we still can reference documents and links and stuff. Basically, the only thing that will change for you is the VintX, because it's your change from RST to markdown, but we keep the same functionality. One of the problems also of what we currently have in RST is that our documentation comes from a lot of sources, which quite often means you get hard errors, because the same links, link names are used in several documents, and that's one of the side effects of an organically grown documentation. But it's where the REST functionality is actually more a hindrance than a help at the moment. What about doc tests? This would not be possible to do anymore in the documentation. We never ever were in favor of that. I did that anyway. No. The doc test for the Plone API? We know about the challenge with Plone API, but we have that already also now, because now building the docs, the main pain point is still as Plone API, and we still have a date with Nates to talk about how we could improve that. Because this is again, from a developer point of view, I completely understand it, but from the main general point of view of good quality documentation, this is just bad, and it's not to blame Nates or anyone else who was ever involved in doing that. It was still awesome, and at this time we did no better, but now it's also time to modernize, improve, and go with time. It's also more or less the opinion of at least the tech writer community that doc tests are neither. They're not a doc and they're not test. Those two shouldn't be mixed. One of the main issues with getting contributors to write good documentation is when they stumble over syntax and being unable to build their own local version of documentation before committing and pushing it up to a repo. Will there be or is there now a tooling available for people so that they can build the docs locally? For the future, the really, it's called Doza CLI, and you can even hook up Doza, for example. I hooked the previous test up to my VS code, so I have a VS code shortcut and then it's building it. For the current version, there's also possibility, but that never gets published because we try to publish it, but then we got someone friendly comments and then we decided, so I decided not to publish it, but it is. It's working. It's even on Dockerhubs, it's regularly updated. I know that this is a pain point, but this is one reason why we try to make it easier and move to a new setup. This is also why the nice thing is, and I know this is really hard to explain to, I'm sorry to say that, more often to developers than to tech writers or people who only want to contribute like a typo. You should, even if you talk about docs as code, this is right, but this is also why, for example, get markdown previews in the editor. If you say, for example, I want to have the markdown preview with the CSS of the documentation side, we can also do that. The main difference is only like the markdown previews and the mark preview only off your side. You don't get, for example, the whole sidebar to the right or the menu or the left, but the question is also, do you really need that if you're just starting editing one file? Why do you need the other files? I can understand that you want to see the main impression generally of the file you're editing. We can do that, that's no problem. If you do not want to run DOSA locally on your setup, then push it to your branch and wait 10 seconds till it's on right on the fly. Currently, there is, well, there's half, but not really published Docker way. There is the old way, but that basically depends on having a functioning Python environment and quite some other dependencies, which basically means it does not work on Windows, and we cannot get it to work on Windows, probably because we're stupid and I only know Linux. I'm sure there's a way, but we can't. It would be great if also developers, or not even developers, but writers, volunteers, other people who have a Windows machine can contribute. That needs to be done. We cannot assume that everybody who wants to contribute to documentation has a developer setup. That's insane. Exactly. There's also one really, really important point. If people want to contribute to documentation, they should be able to do it in an easy way. I don't want to force them to install Python versions, messing with build out, getting frustrated because something is not working. And they're literally the only thing they want to do was change one letter. But being busy trying to figure out a setup for four hours to only change one letter is so demotivating we will lose the people that move away. That is also the reason why we decided to stop all that. That's nice for developers, but not for non-developers or less technical people, so make it easy. People want to commit to documentation and not to debug and build out areas or something. Quick question. Dozer is going to be a similar thing to, for instance, what make the docs running in a docker is when you do make the docs server? Basically, it's more than that. It is one functionality. Basically, you get an old CI where you can say, make docs, make local builds, run tests, run certain tests. There will be a lot of functions. Not from the beginning, but the ideas also we can use dozer for what you do now with Papyrus to fetch different repositories. Basically, then you say, this is my branch, this is repository, this is a part of the desktop where it should end. And then it can also fetch them. So there will be lots of functionality and after, so step by step, we will add them and more. There's room for one last quick question, because otherwise you'll miss your coffee and you're going to need it. Make sure I'm not taking this away from someone else. This is going to start out sounding like a statement, and I promise I'll end up with a question. So I've been to several conferences with people from a lot of other open source communities, and more than a few times they've brought up how amazing our documentation is. And I know it will never be good enough for you. But not just the quality of the documentation, but also the way we do the automated screenshots, the whole infrastructure of the thing. So thank you, first of all. And the question is, are you aware of how awesome you are? Oh, no, thank you. I didn't know. Thank you. Oh my God, I'm flushing.
 Hello everyone, how are we doing?  Okay, let's get started.  Wait, how do I get started?  Oh, it's not turning.  How is it?  How I switch these slides?  Oh, look at this.  Okay, first of all, shout out to Red Turtle.  First of all, thank you for the huge tray of tiramisu.  It's awesome, and we will try our best to enjoy every bite of it,  and thinking about Red Turtle and Plone.  We will do, we will do.  So welcome everyone, let us say it.  And first of all, thank you for attending my talk,  and also thank you to the community to accepting this talk proposal,  and also thank you to the community and to Red Turtle to make it possible that I'm here,  because that was not that easy.  So let's move on.  Okay, first it is a disclaimer.  Basically, this talk is only about the CoreDocs, Volto and Kiewitina.  There's nothing about the training documentation or add-ons documentation,  because these are completely different topics,  and because of that they are not part of this talk.  Also, everything like what we are telling,  or what I tell in the name of the docs team,  is not written and stoned yet. It is basically what we discussed,  and we think it's the way to go, and lots of the stuff, so techniques,  they are also used already since a couple of months in production,  even for some huge companies like certain banks or insurance companies,  and the stuff is working, but then again, I mean,  that is what we came with up, that doesn't mean it has to be completely like this.  So first, let's get into each other.  Who is developer?  Wow, who is technical writer?  Who is a developer who is also forced to write the documentation?  And who of you love that, the drawing writing documentation?  This is less.  And who is already familiar with DocSys code  and using the approach like DocSys code for intensive testing  of the quality of your documentation?  Wow, some already, that's cool.  So there are a gender of today. Can I make that bigger?  Anyway, I look there.  So first, we have a short look about the current status of our documentation.  Second one, we will mention shortly about the Google season of the docs.  Next part, then we will talk about some mistakes  and it's time to lower the barrier for our documentation  because we have some slightly issues there.  Then we move on to the really cool part, which is where they live the future,  what I call Plone X at the moment,  because according to Iriku, I'm not allowed to say Plone 6 anymore.  And this also will cover then the last part,  which is 5, which is basically covering the whole DocSys code approach  and why we should use it and why it's helpful.  So let's start with the current status of our documentation, how we are doing.  And the next quote on the slide, just to make it clear,  it's not from me, that is from one other member.  So our docs are far from perfect,  but considering that there are only less than a handful of people  working constantly on the documentation  and all of that is basically done as volunteer in free time,  there is no company behind it or no one is paying for it,  we are doing not that bad.  And I think that is a really important thing to say, because it's like this.  People in the audience will know me a bit longer,  they also know that I love complaining about lots of stuff,  including documentation and how bad our documentation is.  That's completely true and I still have this opinion,  but then again I also grow a bit and I mean,  we have no company behind it,  taking that we are doing it now free time,  for that we are not doing that bad.  So that is what we currently have, as you know it  and you love it or you hate it  and you love and hate relationship with that.  And there are some things that are not really good  or where we have room for improvement.  I mean, when we came up with the structure and all that,  it's partly because we didn't know better how to do it,  because when we started to do the documentation  we had no clue about documentation at all  because all of us were basically developers.  But we are facing currently some issues with the setup,  starting from that the structure is not really clear and confusing.  We have the weird mix of user documentation  and developer documentation.  The documentation in general is written way too focused on developers,  which is not surprising because 90% of the stuff is written by developers.  We never ever thought about a content strategy or a message strategy,  the only thing what we did in the beginning  was thinking about what's more or less a okay kind of structure  for the documentation.  But it was also then again years ago and like,  the plan changed and also how we use it changed.  So it's not perfect.  Personally, I say it's bad use,  but I mean it's not bad at all for a volunteer project.  So let's talk shortly about campaign points  besides them which I already mentioned.  Like, we have no content architecture or strategy or message or something.  It's confusing, it's too developer focused.  We have lots of stuff which is redundant, outdated,  and it's not available or not matching up at all.  Like for example, using, we have,  and still in the Plone 5 docs,  lots of references from Plone 3 which are never got updated.  If you're talking about the editorial or markup styles and quality,  it's inconsistent, it's completely confusing,  it's way too wordy,  and lots of other things what you could improve.  And then also not forgetting like the whole build and deploy process.  It's super unstable, it's slow,  it's really, really complicated at the moment,  and also it's not that well documented.  So I mean the people who are doing it,  like it's usually Paul or me usually,  we usually are able to do that,  but even I for example getting annoyed  because I never ever bothered to write documentation about that  or at least not proper documentation.  So we sort of fixed that.  So for that I'm really, really sorry  because in some of those parts I was at least involved in writing it  or in making decisions about it,  like the current state of Papyrus,  our deployment tool, or other things.  But it's also good because now it's time to move on and change.  So you also maybe mentioned or recognized in the last year  there was a list going on in documentation  on the less frequent releases of New Dogs.  And this is basically because we split more or less  the documentation team.  So basically we have one sub part  which is the current documentation  like for Plone 5x something.  This is basically at the moment maintaining the build-up  to infrastructure, maintaining to the dogs  and improving the dogs, but it's also getting slow  because we are also depending there  like always on other people and developers.  And from the co-op dogs team basically Paul is doing the maintaining and building.  And I switched more over to like Plone X or Plone 6.  This is like the whole preparation and thinking about structure  and building the new setup which is including editorial style guides,  markup style guides, working together with the Volto team  and even with the guillotine people to thinking about new content architecture,  what kind of message you want to do, user stories,  new build and deployment infrastructure to make it flawless and faster.  And then also like you see on the bottom there's also Google season of dogs  because we all started, Google got granted to the Google season of the dogs  so we are working together with our technical writer Chris  and also then with Kim, Victor and lots of other Plone people  to improving the developer or the experience for starting developers  for the Volto dogs and that was also including lots of talking about content strategy,  message strategy, architecture, what kind of dogs make sense and so on.  And this is basically the Google season of dogs which is still going on.  We are now basically at I think halfway with the whole timing  so soon there will be the first commits with the new blueprint  about the new structure about the developer dogs for Volto.  And this is really important.  We should lower in the future dogs the barrier for contributing to documentation  because nothing is more demotivating and annoying if you, for example,  you are browsing the dogs, you are sporting a typo or a grammar thing  or some just wrong or outdated documentation  and you only want to basically add two or three lines.  Basically you want to create a pull request where you just say I changed line number five  because it was outdated, here's the new write version,  you want to create a pull request and then you want to see it somehow,  somewhere end up online in the documentation.  Currently that is not, that is the end possible.  Currently the whole thing is kind of complicated and really annoying  because we don't have, like, for the average user an easy way to refute the dogs easily  to getting the research out faster and things like that.  So that makes it less fun to contribute.  The really important takeaway here is we should make it as easy and as effortless  as possible to creating pull requests with improvements to documentation  and seeing them as fast as possible online  because that basically creates good feelings and makes people happy  and also motivates them to create more.  But this is also really important, like, I'm going to come.  So you always should remember,  usually you're not writing the documentation only for yourself, there's also an audience.  So that meaning if you write documentation,  never assume that the people who are reading documentation  have your knowledge about certain things that you are writing.  Maybe you are working since 10 years on that and the person is the first time ever reading your documentation.  Also always try to provide background innovation, like, for example, Whiskey.  Different information about Whiskey and maybe a link to Whiskey  or to the Whiskey documentation with blown, edit, not only say use Whiskey,  people will stop reading it, stop continuing because it's just demotivating  and also really unfriendly and hostile.  Be always clear.  Try to be, like, as short, straight to the point,  friendly and clear as possible about what you are writing.  We don't need sentences from, like, 20-something words.  Just make it short, make it easy,  because also think about translation and accessibility.  And then also be consistent.  We still have a huge problem in the blown documentation that we use,  like, for the same functionality, different terms.  And this is super confusing for people.  It's the same, like, if people, like, for example, using,  talking more like developer language,  we have the standard default Docker container for blown  and we have the volatile Docker container for blown done by KitConcept,  but they are not, like, identical.  They are built different, so people are getting confused,  because if you look at the source, it's just different.  So be consistent.  And also, like, we always, we as community,  alter the documentation, we should try to be more friendly and welcoming.  We still have this issue that we always tend to write,  everything is just easy and just do that and things like that.  All the stuff is not easy.  Even, I mean, if you're a developer and you try to write proper documentation,  you will also find out writing properly and good documentation is not that easy.  So, and now, move on to the fun part to the future.  Now that was just ranting about the old setup,  and now let's have some fun about the new stuff.  Are you already asleep or are you still awake and following me?  Okay, cool.  So, like, in the title description of the talk,  I mentioned stunning, so first, maybe I thought I should explain what I mean with stunning.  But stunning for me, it should be always about all aspects of API,  or in this case, API-related documentation.  That means, first of all, it should be appealing for your eyes.  If I look at it, I should be motivated to look at it, because it should look nice.  I don't want to look at an interface from the 80s,  or which is completely confusing because there's way too many information.  I also would like to have some pictures and graphs,  because they make it easier to understand stuff.  I want to have a clear content structure that is completely clear to me,  where I can find stuff, not mixing developer and user interface documentation and other stuff.  I want to have clarity, like what I mentioned already before,  be clear about your wording, be clear about your grammar.  Also really important is good SEO, so think about how you write, what you write.  Because zero is not only good because you're ranking high in Google and people finding you better,  SEO is also good because it helps you to get a better clear picture about your documentation at all.  And the other thing, be accessible.  We have still kind of issues with accessibility.  We should care about that.  Our themes are working with green readers.  They are working for colorblind people.  Another famous thing, people tend to have lovely sentences in your documentation,  like, click here for more information.  And I'm really sorry, this is just wrong.  Stop using click here for more information.  Use a description that people understand if they click on these certain links where they end up,  because this is how screen readers are, for example, working.  Also use this, like as link descriptions in your source code of your HTML link.  I mean, come on, we have to talk 19 almost, so we should do that.  So in one part it's like moving on to Docs as code, and this is now a lot of text.  So what Docs as code basically means is it assumes that you use the same tooling for writing documentation,  which you also use for working on your code.  In the same manner you write on work on your code,  like, for example, using plugins and linters for reporting style violations or errors and other things,  you should do the same for documentation where you check, like with linters,  your documentation against your editorial style guides or your markdown RST style guides and other style guides.  And then depending, of course, on documentation, you always should add some more tests for the consistency of your quality.  That means, for example, if you decide to write your Docs in US English,  check your documentation that you're really using US English or not mixing US English with UK English,  your links are working and things like that.  And why should we use it? Because if we have consistent documentation,  it helps not only the users because they're happy, it also helps the developer,  they're happy because all of us are finding stuff faster,  which also could lead to that we are able to do faster releases.  Also really important, consistency and good documentation creates some kind of trust with the audience,  with the user guy, with the people who are using it.  If people are re-genizing things because, like, think like what we did with README,  when the Docs team introduced a couple of years ago the example, default README,  they were also some resistance and people were complaining,  I want to still use my hitchhiker to Galaxy README and other things.  And these are nice for your private or maybe even for collective stuff,  but think the bigger picture.  Like, if you are, for example, a CTU and you browse the plough and organization on GitHub  and then you figure out that README is always written in the same style,  that the documentation is always using the same wording and the same terms,  it actually creates for me a warm feeling and I started to trust this organization  and these people more because they see that they put effort into it and they try to make it good.  And also take this and think for the bigger picture.  This also is really good for you as a plough provider or a company  because then people look up which companies are involved in contributions to plough  and selling plough and then they also see that you are taking care of documentation  and this is also good for marketing.  Even if you don't like it, it is marketing.  And at the bottom, for example, there is an example picture of running like Docs as code,  as a lintar testing that I don't use here as a link description  and that the second test is that I don't start paragraphs with the words but  and this is just a slight example, they are endless tests what we can do.  And to make it easier because it was always now a bit technical and just too many words,  here is the theme and like as a graph, basically the idea is you start writing in your text editor  and you review by yourself, then you commit to your version control system,  then there are already some checks running, then you may create a pull request,  then CI CD is running against some QHX and if that is nice and everything gets merged,  then the deploy is triggered and the new version will end up somewhere online.  And this is even more because we are not only building cool automatic deploy things to websites,  it is also like we are working on tools to improving the whole experience,  like how to work on documentation.  And this is for example, this is an add-on we wrote for VS Code.  Basically, it is an extension pack for VS Code which basically installs,  I think, 10 different add-ons for VS Code which are pre-configured for writing documentation  according to best practices.  And if you are already, for example, using VS Code, you can also say,  I don't want to have automatically installed in other extensions,  then you can get a link to the detailed documentation and just can decide and do it manually, copy and paste.  And this is also really important because this is where docs are at least for me at starting.  It is not just about this last cool thing with CI CD and deployment,  it starts in locally in your editor and using also linting and tooling in your local editor and on your laptop.  And this is then, for example, how it looks like.  This is an example taken in order for real life.  This is basically like an API of a well-known Dutch bank.  And the technical writers of these banks are using exactly this VS Code setup.  As you can see on the left, there's a markdown spec which they're writing.  On the right, they see your output HTML and on the bottom there, like you know it from your Python linters or other linters,  you get the whole output about what is according to the defined checks, wrong and what you should improve.  And this is basically the same, the same tests as BB8.  BB8 is my personal helping droids which is basically if I do a good commit,  running all these tests automatically like in containers on my laptop,  and it's checking for markdown, then it's checking for accessibility,  it's checking my open API spec, it's checking for broken links,  it's checking for my other style guides,  then it's checking out with Lighthouse for accessibility tooling,  and that takes some time, so be finished.  And then basically if everything is green, BB8 will automatically stage my commits at the commit message,  and then I still have to push it to my repository.  And let's jump a bit more into the details and change, but everything will, all of them will change.  The biggest change, the core docs will move from restructured text to markdown.  So who loves it, who hates it?  So there are a couple of reasons why we make the decisions, and we took a long time to think about it with lots of pros and cons.  So, Spring's and restructured text are not bad, they are working, they are nice,  but the core docs, and I'm really talking about the core docs, Volto and Guillotine,  I'm not talking about add-ons or other things, we use less Python than we used years ago,  we are moving to more different things like using auto-reacts, using other JavaScript things,  using API things, so we also should adjust our documentation tooling for that.  We are also saying we do that because we also want to attract more people,  it does not make sense for us because we are a small and even shrinking community sometimes,  to force for example React developers to write restructured text.  They are no markdown because they are used to markdown, it's way easier for them to write markdown,  the same goes basically for open API specifications and swagger and all the other things.  So we should adapt and make it more friendly there.  Also 99% of the features which are built in Spring's we are never used,  they are awesome and they are nice but we don't use them.  So why make our life complicated and stick with that?  We will use Common Mark as spec for our markdown,  because lots of people were always complaining the big advantage to compare restructured text with markdown,  besides that we are able to do more things with RST if there is an official spec for RST.  That is kind of true but not really anymore because Common Mark is getting to be the official spec for markdown.  The whole board from Common Mark is quite active and also the specs which they came up with,  they are really really nice.  So for us that's also important, they are more than enough.  It's covering all our use cases and yeah, for that is perfect.  So the other thing, I mentioned that we are stuck using Spring's,  we will move to Gatsby for building and deploying the documentation  and there are also different reasons why we decided on that.  First of all that is also what WOT was using, what lots of other React projects are using.  Because we suffer now, for example, really hard from that,  that we are not able to do proper Spring's changes and buildups,  because there are not enough people who have time or their energy to do it.  With Gatsby we can get more people jumping and it's also some technique that they know and what they love.  And there are also lots of add-ons and libraries already there anyway,  so it's easier to get changes and we are more flexible.  And also this is really important, there are more people able to maintain the stuff.  It's not basically the bottleneck, it's not Paul or me or two other people on a Spring's,  then basically it's really the responsible from the whole community.  We get a new build CLI.  Some of you may already know that at the moment we are using Papyrus,  which was something what we set up a couple of years ago,  and then it changed into some Frankenstein set up with lots of different Python  and bash scripting and weird configuration files.  It's complicated, let's keep it by that.  And this is now for example interesting because there is no decision made.  So basically I tried out or I'm still playing with one JavaScript based one,  where I use Oaklyph which is from Sageforce.heruco,  and the other one basically it's Golang based.  And they are pros and cons to both of them.  And like if you use the JavaScript base, there are more people from what's a 100 JavaScript  who can help do it, so it's easier to contribute because more people know JavaScript  or note in this case, but the less cool thing is they are less native integrations  to like for example container APIs for Docker, for Kubernetes, for Firecracker  and things like that.  I personally I would go with Gol because I got all this native API integrations  and for me personally it's easier, but then again it should not be only about me  and what I like or prefer, sadly, sadly.  And this is also about now why I'm basically asking like the community,  maybe the decision.  If people are saying we are helping and we know JavaScript and we willing to help,  it's fine, I'm completely cool for that and then we go for it.  But if just like sadly quite often people are only complaining but not jumping and helping,  then I will just go with go and you have to live with it.  I'm really sorry.  And the reason why we did not choose Python, it's quite basic.  Python is nice, but still to today I'm not able to get native binaries from Python.  To run a Python binary you still need to have Python installed on your machine.  And the idea is I want to have it as easy and as for less for other people.  You don't have to have something like Python, virtual and for other things installed on your machine.  Just download the binary of CCLI and you can run, deploy and be happy with whatever you like to do with it  or what you can do with it.  The other thing, we will start hosting on Netifly.  That's nice because it's fast.  We're getting automatically CDN and we have one less server to maintain ourselves.  And the really, really cool feature is we get preview of branches.  That means if you create a branch of your documentation and you write stuff and then you push the branch to GitHub,  you automatically get in GitHub and URL which is pointing to Netifly where you can go  and then you see there are compiled run on the HTML of documentation of your own branch.  With those are CLI and the setup of the editor, like VS Code in this case,  you can still do it locally also.  But this also makes it easier because maybe you're not using VS Code, you're using, I don't know,  Nano or Joe or some other weird editor and it's not configured yet.  So it doesn't matter, write in it, push the branch, go to Netifly, preview your branch there.  If the branch gets merged, then the preview branch gets automatically deleted, so that's also cool.  And it makes it also easier if you want to ask other people to review it, so it's less work and it's faster.  And this is basically how it will look like in GitHub, it's saying the preview deploy is ready  and then you can click on it and then you're ending up on your branch.  We will move to GitHub action for continuous integration.  The nice thing is all the checks we're using, they are container based,  so you also can use them with your Jenkins, drone CI, build kite, AWS pipeline, whatever continuous integration you prefer to use.  But for the docs self, use GitHub actions because they are fast and working for us.  And this is for example, like the debug output of a GitHub action which is running a link check.  At the bottom, you can see it is red, that's saying it fails because I wrote a poll on wrong, I wrote it with two ease.  What we also do with CI CD, to make it clear, it will not be only link check, we will run currently something like 20 different checks  for markdown quality and the quality of the content.  And we also use it to run lighthouse checks once a week at the moment on your site.  And there's no decision made how we configured, like if the docs team gets a mail with a link to download the latest results or something.  But this is really nice because it gives us more insights about the performance of the site, accessibility, CO and stuff.  So if we do that over a long time, we can see how we are increasing or decreasing and it's nice to get a better overview.  And also one reason why there were less contributions to the documentation is because we are writing on a completely new blown documentation guide.  The idea is that it's one guide to rule them all.  This is a completely markdown style guide and a total style guide about wording, terms, length of sentences, lines, why you shouldn't use certain words and stuff like that.  It is almost finished. I think we are now at 99% or 98%.  So there are still two or three tests for the style guide itself, something missing.  It's good to go. It's also nice. This style guide got a review by technical writers from other companies.  For example, we got a review from Sarah Maddox from the tech team from Google and from another person from the Microsoft Azure docs team.  And they loved it. I mean, still it's not perfect, of course, but the feedback was really, really positive and they even took some parts of them over to their own style guide to be sure it was Kubernetes to be clear.  And also what we will do, we will do content splitting.  At the moment we have just Docs.plonar.com. There you have developer documentations and user documentations.  And like I already mentioned, this is just kind of confusing and not clear from the content structure.  So we will split that in Docs.plonar, which will be end user documentation for Volto and end user documentation for our current front end.  Like if you want to create a site, click here, create a site, blah, blah, blah, blah, blah, how you set, do the configuration.  All the developer documentation, meaning REST API, development add-ons, theming, Volto, back end, Guillotine, will go to developer.plonar.com.  This is nice because there's also a common setup and standard for lots of other projects, open source or commercial using it.  People know that, they know what to expect.  And this is also why we decided because it also makes it easier and faster to add changes and deploy stuff.  And another fun picture at the bottom is the same link check, but then he's passing for a Plon document, but this is running on a drone CI.  And shortly about content structure, these are only just some mockups.  What I created, I am really bad with creating mockups, but it doesn't mean that it will look up in the end, look like this, just to get some kind of idea.  Basically, the idea is, for example, if you go to developer documentation, you get clearly like the topics.  I want to have Volto, REST API, Guillotine, or maybe developing Plon Core or whatever we add there.  And then, for example, you click here on Volto and then you get a really clear page, not too much stuff around, not too much colors.  I mean, we should add some colors, but make it clear that the content is important.  It's not about colors and fancy pictures all the time or gifts or whatever.  The content is the main message what we want to divide.  We can still have posts about Brittany, docs, and other things and lots of glitter, but we have to find a way to do that properly.  And because of that, we're also getting a more flat structure, which is nice because we're getting shorter domains.  So, for example, docs, Plonork, external, Plonup, Dexterity, docs, advanced, validators, which is really a mouthful word change to develop other Plonork Dexterity validators.  This is easier for people to remember. It's better for CO, and it makes me a lot more happy.  And also, we will start running like, and at the bottom, you will see this basically, a standard test using Spectral against my Open API spec.  We will also start using that for Plonrest API and for Glutina, but not as part of the docs team.  And in case people do not know me, that is basically, that is me, talking about fancy job descriptions.  My officially job description at the moment is content architect slash docops engineer.  And basically what I'm doing is I'm working on API and API-related documentation for high availability.  I hate this word.  API is gateways.  Think about APG or MuleSoft, and then you're talking with banks or insurance companies, and you have millions of requests per second.  And that was all.  So who is completely scared? Who hates it?  Who is not agreeing with everything?  Scared is okay.  Yes.  We have time for questions.  As ever, I will ask you to indeed ask questions and not give a monologue, because that way, if you want to hold a monologue, there's lightning talks.  And wait for the microphone because it needs to be on tape.  Or how do you call it in the digital age?  Hi, thanks.  I know you just said that images and glitches are not everything, but in good documentation, we do tend to add screenshots and pictures.  Oh, sure.  Sorry, I didn't mean that.  I know.  But how easy is that in the new documentation system to add?  Way easier than current, because we are using, I forgot the slide about that.  We will use Puppeteer for that.  And writing things for Puppeteer, you can choose if you want to do it from a command line, or if you want to do it via an editor, for example, in a web-based editor, if I'm right.  Yes.  We're using Puppeteer, which is well maintained, but there's also a very nice editor that does clickity-clickity.  Basically, you click your text together, and then it spits that out as a command line file.  So even I can create a test just by clicking.  And then I say download this as an XML file, and it will repeat itself for automated screenshots.  And these things are run as also as GitHub action once a week at the moment, then as Chrome, and then we embed the pictures to the right places.  The base idea is still the same, what we're doing with the robot test at the moment.  It's just easier, because you can choose to use an editor, or like me, just do it from command line.  But it's more stable and faster than robot tests, for this case at least.  Sven, one question.  You're switching from RST to command mark, from Sphinx to some other systems around, and did you have something like a preview for us?  How it looks like to write just the normal documentation, how to link in between pages to get...  Yeah, well, all the stuff we have with Sphinx at the moment, where you can include code, highlight the stuff you need and everything.  This is partly already covered in the Star Guide, and for the rest we will publish it at the moment when we really go online with it.  But the idea is basically it's working like normal markdown things, that means as we're right, there's a bit less functionality than what you get with Sphinx out of the box.  But after comparing all the pros and cons, we decided it's worth, because adding links in markdown is usually, at least if you use a pre-configured editor,  or even if you do it from hand, easy and fast, and we still can reference documents and links and stuff.  Basically, the only thing that will change for you is the VintX, because it's your change from RST to markdown, but we keep the same functionality.  One of the problems also of what we currently have in RST is that our documentation comes from a lot of sources,  which quite often means you get hard errors, because the same links, link names are used in several documents,  and that's one of the side effects of an organically grown documentation.  But it's where the REST functionality is actually more a hindrance than a help at the moment.  What about doc tests? This would not be possible to do anymore in the documentation.  We never ever were in favor of that. I did that anyway. No.  The doc test for the Plone API?  We know about the challenge with Plone API, but we have that already also now,  because now building the docs, the main pain point is still as Plone API,  and we still have a date with Nates to talk about how we could improve that.  Because this is again, from a developer point of view, I completely understand it, but from the main general point of view of good quality documentation,  this is just bad, and it's not to blame Nates or anyone else who was ever involved in doing that.  It was still awesome, and at this time we did no better, but now it's also time to modernize, improve, and go with time.  It's also more or less the opinion of at least the tech writer community that doc tests are neither.  They're not a doc and they're not test. Those two shouldn't be mixed.  One of the main issues with getting contributors to write good documentation is when they stumble over syntax  and being unable to build their own local version of documentation before committing and pushing it up to a repo.  Will there be or is there now a tooling available for people so that they can build the docs locally?  For the future, the really, it's called Doza CLI, and you can even hook up Doza, for example.  I hooked the previous test up to my VS code, so I have a VS code shortcut and then it's building it.  For the current version, there's also possibility, but that never gets published because we try to publish it,  but then we got someone friendly comments and then we decided, so I decided not to publish it, but it is.  It's working. It's even on Dockerhubs, it's regularly updated.  I know that this is a pain point, but this is one reason why we try to make it easier and move to a new setup.  This is also why the nice thing is, and I know this is really hard to explain to, I'm sorry to say that,  more often to developers than to tech writers or people who only want to contribute like a typo.  You should, even if you talk about docs as code, this is right,  but this is also why, for example, get markdown previews in the editor.  If you say, for example, I want to have the markdown preview with the CSS of the documentation side, we can also do that.  The main difference is only like the markdown previews and the mark preview only off your side.  You don't get, for example, the whole sidebar to the right or the menu or the left,  but the question is also, do you really need that if you're just starting editing one file?  Why do you need the other files?  I can understand that you want to see the main impression generally of the file you're editing.  We can do that, that's no problem.  If you do not want to run DOSA locally on your setup, then push it to your branch and wait 10 seconds till it's on right on the fly.  Currently, there is, well, there's half, but not really published Docker way.  There is the old way, but that basically depends on having a functioning Python environment  and quite some other dependencies, which basically means it does not work on Windows,  and we cannot get it to work on Windows, probably because we're stupid and I only know Linux.  I'm sure there's a way, but we can't.  It would be great if also developers, or not even developers, but writers, volunteers,  other people who have a Windows machine can contribute.  That needs to be done.  We cannot assume that everybody who wants to contribute to documentation has a developer setup.  That's insane.  Exactly.  There's also one really, really important point.  If people want to contribute to documentation, they should be able to do it in an easy way.  I don't want to force them to install Python versions, messing with build out, getting frustrated because something is not working.  And they're literally the only thing they want to do was change one letter.  But being busy trying to figure out a setup for four hours to only change one letter is so demotivating we will lose the people that move away.  That is also the reason why we decided to stop all that.  That's nice for developers, but not for non-developers or less technical people, so make it easy.  People want to commit to documentation and not to debug and build out areas or something.  Quick question.  Dozer is going to be a similar thing to, for instance, what make the docs running in a docker is when you do make the docs server?  Basically, it's more than that.  It is one functionality.  Basically, you get an old CI where you can say, make docs, make local builds, run tests, run certain tests.  There will be a lot of functions.  Not from the beginning, but the ideas also we can use dozer for what you do now with Papyrus to fetch different repositories.  Basically, then you say, this is my branch, this is repository, this is a part of the desktop where it should end.  And then it can also fetch them.  So there will be lots of functionality and after, so step by step, we will add them and more.  There's room for one last quick question, because otherwise you'll miss your coffee and you're going to need it.  Make sure I'm not taking this away from someone else.  This is going to start out sounding like a statement, and I promise I'll end up with a question.  So I've been to several conferences with people from a lot of other open source communities, and more than a few times they've brought up how amazing our documentation is.  And I know it will never be good enough for you.  But not just the quality of the documentation, but also the way we do the automated screenshots, the whole infrastructure of the thing.  So thank you, first of all.  And the question is, are you aware of how awesome you are?  Oh, no, thank you.  I didn't know. Thank you. Oh my God, I'm flushing.
Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_0_263.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_264_311.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_312_395.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_396_803.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_804_55295.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_55296_55775.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_55776_56255.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_56256_56303.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_56304_56471.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_56472_56591.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_56592_57299.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_57300_58007.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_58008_58127.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_58128_58187.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_58188_58475.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_58476_59351.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_59352_59399.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_59400_59687.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_59688_59735.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_59736_60239.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_60240_60287.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_60288_60851.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_60852_61943.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_61944_62363.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_62364_62531.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_62532_62579.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_62580_62711.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_62712_63311.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_63312_63743.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_63744_63887.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_63888_64139.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_64140_64199.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_64200_64307.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_64308_64427.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_64428_65159.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_65160_66863.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_66864_67571.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_67572_68399.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_68400_68519.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_68520_68579.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_68580_68723.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_68724_69455.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_69456_70079.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_70080_71435.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71436_71519.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71520_71567.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71568_71615.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71616_71675.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71676_71747.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71748_71819.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71820_71867.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71868_71915.png Sven_Strack_-_How_we_use__Docs_As_Code__to_enginee_QQgW_bkOVtE_71916_71962.png