 My first ever documentation contribution was actually to Drupal, but now we're going to talk about using Drupal to manage documentation instead as Kiti Radevich from Providence. Thank you very much. So, hi everyone. Just let me know when you can't hear me in the back. I will try to speak up. So, yeah, it will be a session about docs like code in Drupal. And first, I would like to say some words about the docs like code approach. And after that, I would like to tell you about our open source product in Drupal, which uses this concept. So, I'm Kiti Radevich and I'm a product owner at Pranovic. And I'm working on developer portals mostly and I'm the product owner of this open source tool that I'm going to talk about. And why docs like code? So, what does docs like code mean? Docs like code is basically a workflow for creating documentation and generate documentation in web format. First of all, when talking about docs like code, the main, the key point is to, is using version control system like GitHub. But of course, you can use other services. We use GitHub in our product. And thanks to GitHub, it's very easy to keep pace with the code changes. So, when the code changes, documentarians can drag the changes and see if the documentation is not updated to the code changes and update them according to. The code. After that, yeah, it's a unified collaboration environment. Because documentarians don't have to learn a new tool for documentation creation. So, GitHub is very easy to use. It has a lot of documentation about how to use it. So, it's very easy to learn the tools that GitHub provides. Other than that, GitHub means collaboration. So, the contributors can collaborate using the GitHub UI. And of course, anyone can contribute, anyone who has access to the repository. And this doesn't just mean technical writers, but also developers. Who can, for example, write notes about the code changes and technical writers can extend the documentation and fix the typos and make sentences from the notes. And thanks to GitHub, it's very easy to integrate it with a continuous integration tool. And, for example, Jenkins or Travis CI. And it's also useful for static site generators. Because static site generators are the well-known tool for creating docs, using this docs-like-route concept. And static site generators basically grab the content, mostly written in Mardown, and templates. And they create the final static site in HTML and with all the assets. Yes. And this continuous integration tools can trigger the generation of documentation. But sometimes static sites are not enough. So, with CMSs, we can substitute the role of static site generators. And with CMSs, we use the same workflow for creating documentation. But at the end, the docs are displayed using the CMS. And, yeah, I want to use a CMS because there are specific use cases when it's beneficial using a CMS instead of a static site generator. For example, if you have as much content as the static site generator takes too long time to create docs. And with CMSs, we can reduce this time because CMSs doesn't regenerate the site itself. They just add new content to it. Other than that, it's also useful when you don't need just docs, but you also need other content like landing pages or marketing or blog content. And CMSs have great tools for creating landing pages. For example, in Drupal, we use the paragraphs module for landing page creation. And it's very easy to use. And, for example, content writers can create landing pages without writing actual HTML. And it's also useful if you need a search because, yeah, static site generators usually have a simple keyword search. But as they don't have a database behind the static site, they cannot provide advanced search functionality. So with the CMS, you can also have an advanced keyword search. And you can also use faceted search for field and index categories. Yeah, next one is a raw-based access contra. This basically means that you don't have to create separate pages for each audience. So, for example, you can have all the docs for private usage and for internal usage and also for partners. And you can control the access to the content using the CMS raw-based access contra functionalities. You can also create widgets that can interact with the API itself. So if you are documenting an API and you are importing, for example, with open API spec, you can also create a tool for trying out the APIs on the fly. And, yeah, last one is about gamification. So gamification is for encouraging docs to be excellent and not just to write docs because the documentarians need to write docs at the end because developers won't understand the product without docs. So they need to provide something just before releasing a product. But with gamification, you can write docs from the beginning. So you can encourage your developers and your documentarians to always improve the documentation. For example, this can include specific rating features. So if someone likes the docs and rates it somehow or marks it as useful, then you can evaluate your documentation and see which pages are useful and which pages have to be improved. Okay, so now I would like to talk about the open source product we created in Drupal. So we already had something before meeting docs like code. The first version had a UI for adding the markdown content to the documentation. So as you can see, on the UI, the documentarians were able to add the title and the body markdown format. And display it as a one-page format with navigation on the left. And we also wanted to integrate with the OpenAPI spec. And in the first version, we had a file uploader on the UI. And content editors could also add additional tags and version to it. And it has a very simple layout that can be seen on the left-hand side. But after adapting docs like code, we created a step-by-step form for importing docs at the same time. In the first step, GitHub account has to be selected or you can add a new if you want. The second step is choosing the repository. You can either add public repository or choose a private one based on the account you selected. The third step is about choosing the files to import. On the top, there's an import title can be specified. And then you can choose the content to import from the repository. As you can see, there are markdown and then the assets imported into the markdown content. But you can also see that there's an adjacent file which is in OpenAPI spec. So you can import all your docs at the same time basically. After choosing the files, there are some configurations that can be made to the import. For example, as markdown files have the same extension, we created a plugin-based markdown format selector where you can choose which markdown format you use in your docs. And it can be also extended by other formats. And on the downside, you can select how the swagger or OpenAPI spec files are ended. So it's necessary because if you store your documentation together with your code sources, it can happen that you use JSON format for other configurations or other settings. So we created this kind of solution to separate OpenAPI specs and other JSON or general files. And update settings. So this is about publishing changes automatically, which means that Drupal imports the changed content with its Chrome service, which runs periodically. And it detects the changes and it imports the docs when the change happened. And if this option is selected, then the changes get automatically published on the site. In the other case, you can review the changes and publish the docs manually. The next step, there's an option to choose the hierarchy where the documentation will be imported. So if you combine separate docs into one documentation hierarchy, you can do by selecting the same hierarchy and order the pages later. So after importing the docs, this is how it looks like. So the order is based on the alphabetical order of the files. And they can be ordered with this Drupal drag-and-drop UI. And after that, it looks like this. So it creates one single page from all the imported docs with navigation on the left-hand side. And for the OpenAPI spec, we use the Swagger UI as a renderer for now, because it's very easy to use and to do some basic teaming to it and it looks nice. But we would like to create a more advanced Drupal-based, an entity-based OpenAPI specification, which splits up the OpenAPI specification into different entities and defines the relationships to each other and render the documentation with this entity-based system. Yes, and the markdown docs are rendered in simple HTML. And we also included an Edit on GitHub button next to the imported files, below the imported files title. This allows users to go straight to the repository where the documentation was imported from and made the changes there. So the changes were happening in the repository. The Drupal is only for rendering the docs. With this chart, I visualized the workflow for creating the docs like or the approach docs in Drupal. So the first step is to upload the docs to GitHub and import docs into Drupal, order them in Drupal and publish them. This is basically what I just showed with the screenshots. And after that, the updates to documentation can happen to Waze. The top part is about if you want to change the docs, you visit one of your docs in Drupal. Click on the Edit on GitHub button, push your changes to GitHub. These changes get reviewed and approved by one of the contributors or one of the reviewers. And the changes get merged into the documentations repository. Then the changes can be published automatically basically in Drupal. The other way is another way to update the docs is when another user finds an error or some typo in the docs and visits the documentation, pushes the corrections or the changes to the docs, you review the changes and merge the changes into the repository, then it gets automatically updated and published on the Drupal site. There's a very important use case of this Drupal-based documentation publishing. And this is about contributing to upstream projects. So usually there's problem with using upstream docs and changing upstream docs because usually happens that people pull the docs from GitHub or fork them and make changes to the upstream docs locally basically without contributing back to the base repository. And with this solution, we can encourage people to contribute straight back to the upstream docs. So if you find an upstream documentation in GitHub, you can import it and you can also mix it with your docs. But the key is that after publishing the upstream docs in Drupal and changes has to be happened in the upstream docs, then the visitor goes straight to the repository of the upstream documentation and the changes can happen right there. And after merging the changes, our documentation can be updated based on the changes in the upstream documentation's repository. The other way to update the upstream documentation can be happened externally so without visiting our site. And if someone finds a change to be made on the docs, the changes can be applied in GitHub merged and then our docs are also updated. So it doesn't matter if the change is triggered by visiting our docs or other place where the upstream doc is published, our documentation will be always updated and upstream docs will get the contribution. Yes, and we have this open source product, we're still planning to implement other features than we have now. So the open API specification is a bit granular in our system, so we would like to simplify it a bit. As I said, we split up the open API spec into multiple Drupal entities and it seems a bit granular right now. So we want to simplify it a bit. Yes, I already mentioned the try it out function that CMS can provide. Unfortunately, we don't have this functionality just yet but we are strongly working on it because it's a very great way for developers to try out the APIs and just copy paste the code and use the APIs very easily. Third one is about standalone service for importing docs from Git-based repositories. So we would like to make it vendor-independent and implement a simple external service for importing documentation. Yes, and as I said, the documentation structure is ordered alphabetically by default. So we would like to use the markdown data standard map files format for setting up the hierarchy of the documentation. As it's JEMO based, so it can be very easily integrated into Drupal 8. And it's very easy to use because it uses markdown. Yeah, and our open source product is split up into two different Drupal modules which can be downloaded or pulled from GitHub. You can find them there and if you have any questions just come to me and I try to answer them. Thank you. Time for questions. So, yeah, if anyone has any, then take it. Do you have plans to support OpenEP 3.0? Sorry? OpenEP 3.0? It's currently supported version 2.0 OpenEP specification, right? Yes. So do you have plans to improve the OpenEP 3.0? Yeah, we are planning that. But we haven't finished the 2.0 version so far, but yes, we are planning. Yes, and we are also planning to import code snippets right from the repositories and code sources basically. Yes, so when we started our product, we were thinking a lot about which format to support and we chose OpenEP because it's a very commonly used format. But yes, we are prepared for the extension so, yeah, later we may support other formats as well. For the documentation, yes, it's my town. But it's a plugin-based importer so basically any format can be imported. Yes. What do you talk about upstream documentation and downstream? The downstream one, do you have any changes like maintain a slight difference in documentation? And if so, how do you deal with it? Like, you must just have to deal with merge conflicts sometimes. When importing upstream docs, you just pull the documentations and you don't change it locally so that shouldn't happen any conflicts. So when you talk about upstream and upstream, they are totally downstream and upstream are not connected technically. They are just displayed in the same documentation page. For the content? So the downstream is not the way, so it's not forked basically. Just downstream means that you display the content in your site. So you should fix it up right now? No. We have time for maybe one more before we just take a quick dead room break. Okay, thank you. Thank you.