 documentation for users with AsciiDoc and Etoro. Welcome to my talk at the DEVCON device. My name is Alexander Schwartz, and I'm a Principal IT Consultant at MSG. It's all about empowering your users with documentation so they get their work done. To do this, you need to keep your documentation content up to date. You need to keep your content consistent, and when you publish new features of your software, you need to publish updated documentation at the same time in sync. AsciiDoc and Etoro help you to do that. Etoro provides you with an online documentation site. You can fully automate the process so you can be up to date all the time. The documentation is searchable and topic-based, so your users can enter a search term in the search field and get a list of all the topics that they can then read. You will have a navigation outline that users can browse, and you can have cross-references within your pages to direct users to related content. All your content is grouped by a version and component. Grouping it by a version allows you to direct the user to the documentation that matches the version of the software they have installed. Grouping it by a component allows you to address different kinds of users with different kinds of content. Etoro provides you with the publishing tools and the documentation structure. The documentation is structured into components and modules. AsciiDoc will collect content from multiple Git repositories and branches, and will convert all the AsciiDoc content it finds to HTML output. It merges the HTML output with a UI theme and creates aesthetic sites. The key benefits are that it has a very fast conversion built on top of Node.js and minimal dependencies. It's quite modular and extendable, so you can add the things you need, even if they are not part of Entoro Core. Entoro builds on top of AsciiDoc and AsciiDoc. AsciiDoc is the language of the content, and AsciiDoc is the toolchain to create HTML from AsciiDoc content. AsciiDoc is frictionless writing using plain text. Therefore, it's well suited to be checked into Git, so you can also cherry-pick it and compare it with older versions. It has a feature-rich syntax for technical documentation. It has great support for lists, for tables, for listings and call-outs, so everything you need to write really good technical documentation. It's been around for more than 15 years and alive and kicking. Last year, a standardization has started at the Eclipse Foundation. AsciiDoc is the toolchain to create HTML and other output formats from AsciiDoc. It's open source, it runs on Java, Ruby and JavaScript runtimes, and it powers Entoro's AsciiDoc to HTML conversion. Today will also be about writing in your IDE. When you write inside your IDE, you will stay focused as you don't need to switch any apps. You will get the best support, collaborate using version control because IDEs provide great integration with Git. The IntelliJ AsciiDoc plugin provides both Entoro and AsciiDoc support. Full disclosure, I'm the current maintainer of this plugin. If you have any questions, please direct them to me either by email or using the GitHub issue tracker. Let's dive into Entoro a bit more. Let's dive into the structure. As I said, Entoro has components. An Entoro documentation site can have multiple independent components. Each component is identified by name and version, and each component can have multiple modules. And you can have cross-references between components and cross-references across modules. Each module has a predefined structure. There are pages, images, examples, attachments and partials. Partials are content snippets that can be included in multiple places. This helps you to make your site consistent as you don't need to copy around content. An advanced feature is that a component can be distributed across multiple folders, branches and repositories. When you start small, you might not need this feature, but if you have a bigger documentation project, this comes in very, very helpful. Looking at the Entoro process, the user just runs Entoro and Entoro does its job. But what does Entoro do? When the user starts Entoro, it loads the playbook with a list of all the repositories and branches that the content is. Then it clones these git repositories. It creates HTML output from all the Asciidov content in there, merges it with the UI theme and the customizations. Optionally, it can also create the search index and other things. And finally, it creates an output folder with a static site. This static site can be hosted on any web server. You can also publish it on a content delivery network or send it as a zip file to your customer. So what are the roles when you set up a new documentation project with Entoro? Well, you need to have some authors. They structure and write the content for your documentation site. They need to be familiar with Git or willing to learn to work with Git because this is the way you collaborate with other authors. All the content they write, they write in Asciidov. You would need to have some docuOps people who are familiar with automation and infrastructure. They set up a Git repository, direct YAML for configuration. They set up a package JSON for some version management and set up continuous integration for automation. Last but not least, you need to have some web developers who can create a website. They need to know about HTML and CSS to customize an Entoro theme. Depending on the amount of customization you wanna do, JavaScript will come in helpful. The first steps to set up an Entoro site would be that the writers create the first component with a folder structure like this, create an Entoro YAML and give the component a name and a version. Then create the first page in the pages folder, create some navigation entries in a navigation file and reference that in the Entoro YAML file. And the docuOps people, they will install Entoro, either using NPM or package JSON file. They will create a playbook to generate a local preview site for the authors and another playbook to publish the site on the internet. The web developers, they will copy an existing UI theme for Entoro or they will create their own and provide the necessary customizations, for example, for the right header and the footer so that they have the right content. So now it's demo time. Let's see how this works using the IntelliJ Ask a Doc plugin. IntelliJ Ask a Doc plugin uses Entoro for both the user's guide and the contributors guide. So this is the IntelliJ Ask a Doc plugin. This git repository contains both the documentation and the source code. I chose to put the documentation in a folder called doc but you can name it anywhere you like. I open up this folder and see two folders. One is the contributors guide. One is the user's guide. Each of these is one Entoro component. And when I open up the user's guide, you see the typical structure of a component. I see the Entoro YAML file and a folder called modules with all the modules in this component. They open up this component and see the mandatory elements in here. That's the name of the component and the version of the component. I can specify additional optional attributes here being like the title or I could mark it as a pre-release. I can define the start page. Now I open up the modules folder and see that there's a navigation file in here. Once I open up this navigation file, I see a list of navigation items. They are on different levels with the usual Ask a Doc syntax. What I reference here on the left in the source code is only the name of the file. On the right, I see then the navigation title. I click on the installation a doc and now I'm in the installation file. I see the title here that's also part of the navigation. I see my sections here but they have IDs that I can reference later. This is the text with a preview. I can scroll them independently but once I place my cursor, preview scrolls to the location of the cursor. Here I have a partial that's being included here. A partial, a common snippet of text describing the Java FX preview that I use in multiple places and I include it like this. I can reference other pages using Xref or I can use local references within this page like this. The text editor of the Ask a Doc source behaves like any other text editor in an IDE. You can fold sections. You can navigate to references. You have auto-completion. So if I want to add a reference here, I will get an auto-completion of all IDs that are within range. This behaves really like code with all the auto-completions and validations you can mark produced will then appear in a to-do list. So all the convenience elements you would expect from an IDE are here. I can also choose the structure outline view. So the same structure that I see here and that I can fold, I can get myself an overview about this section by expanding and drawing down through the sections of this document and use it to navigate within the source code. So it's a full-featured editor as you would expect. This editor also contains well-checking and grammar-checking. So we are now looking here at the key map. The key map shows the use of tables in Ask a Doc. So I defined the width of the different columns, the kind of grid I want to show here, formatted content within a cell with keyboard macros. And once I switch to the preview, so there's both a side-by-side preview, but here as I have a reduced screen resolution for this demo, I switch to a preview-only mode and the author can prove read it and see that the formatting are all correct. As an author, when I check out different components in different branches and repositories, I can use all functionality of the IDE and I can get a good preview of the content, the navigation and irrelevant cross-references. Having both a docs and a code in one grid repository helps me to keep them both in sync when I, for example, look at the history of the skitter repository and search for a specific issue, in this case, 556, and have a look what kind of changes were committed for this one issue. I see so that there are some documentation changes here regarding a style sheet, there's a documentation change for the change log, there are code changes and there are test changes. This makes it straightforward to do code reviews on this ticket. As you can check out from your list, there has been a code change, there has been a test change. The documentation has been updated and it changed log as well. Everything looks fine. Let's look at the second repository. The second repository contains the playbooks for Antora and shows what a docuOps person does to automate the build for the documentation. So this is now the repository for the website. Looking at this, there are several files and folders related to Antora. One is the Antora playbook that publishes the information on the final site. Looking at this file, you see there's a title for the site. There's a URL where the docs will be accessible. There's a start page. So I set it to the index adoc file in the user sky, that should be the start page for the documentation and I point it to the git repository where it finds the documentation that it should render. There's a URL for the git repository and there are two start paths for the two components we've seen earlier, plus the branch where it should look for it. So this defines where the content is and now there's a section about the UI. There's a URL with the zip file with all the default UI elements that I'm about to use, plus a folder with a supplemental UI where I override some of the files in the standard UI bundle and the final output will be created in the folder called site slash docs. Below I can also define extensions and attributes that should be global to the site. In this playbook for the final site, I define where to fetch the sources from from a remote location, but when I want to render a preview locally, there's a little bit customized authors playbook. When I open this file, they look very, very similar, but this file picks the sources not from a remote git location, but from a local git location that's relative to this file. So this assumes that an author who wants to render a preview checks out this git repository just next to the Ask a Doctor IntelliJ plug-in git repository. That is the same start path with a difference. In the previous playbook, I had this branch just point to the master branch. This one points to head, meaning this should be the currently checked out sandbox of the other git repository. So this playbook will render the contents of this git repository, even if they're not yet checked into that git repository. This makes it very handy to render a local preview. All the other elements are basically the same like before. To set up Antora, I prefer setting up a package JSON file that allows me to specify all depth dependencies for Antora and all the extension that I am about to use here. So this Antora Lunar is, for example, the search index that I'm using on this site. Ask a Doctor Cookie allows me to render diagrams within my documentation. Up here in the section scripts, there's a predefined script for the authors playbook and the site playbook with all the necessary parameters that I wanted to have in here. There's also a command in here to start up a small local HTTP server to get a real good preview of the rendered site. These commands are later called from a build script. I chose Bash to write this in this case. This will first run Jekyll for the start page, will then set some environment variables and finally use yarn to run the build. So this full build script includes both building a start page using Jekyll and Antora, runs on Netlify and on for about two minutes. And after that two minutes, the site is live. After we now looked at the roles of the writer and the docuops person, you now look at the role of the web developer. The web developer is customizing the UI theme of Antora. What do they need to do? The UI bundle contains all the default files for, for example, CSS, for images, for driverless scripts and layouts and partials. And the minimal setup, if you're using the standard Antora UI would be to override the partials for future content and header content. So for example, if I compare the footer content, you see here on the left, there was a text, this page was built using the Antora default UI. So this has now changed so that it matches this documentation repository. It lists the contributors. It updates the relevant links. This is while the minimal change you want to do at least for the footer and the head would be similar. Looking at the head content, old and new, you see that there were original navigation items where I added a logo in here. I also added a doc search snippet in here. And usually you want to have navigation items that are then project specific. So I decided to link the quick start guide and the contributors guide and user's guides in here. These are the two snippets that you want to override and you set up a new project. I added some more customizations as you see here. I added a lightbox element. I updated the scroll bar to match my project. So this is the way you add customizations to the Antora UI. Looking at the resulting page. So this is the web page for the IntelliJ ASCII doc plugin. The start page has been created using Jackal as it gives me more flexibility to create this page compared to the very, very structured Antora layout. Where I now choose the user's guide here. This is the Antora component for the user's guide with its outline on the left. There's a link to edit this page. There's an outline of the current page. We've looked at the plugin installation before. This is a text as it appears on this page here. If I choose features key map, you see also the key map like it appeared also in the IDE. And if I scroll to the very end, we see down here the footer as I updated it. So this is the end of the tour. Let's go back to the slides for a summary. It's all about empowering your users with documentation so they get their work done. Ask a doc on the Antora, help you here. They help you to keep your content up to date as you can collaborate as a team using version control. They help you to keep your content consistent. So each component version measures a software version and you can do all the deduplication of content. For example, using partials that you need to provide a really consistent experience for your users reading your documentation. And Antora provides it with the tools that when you publish new features for your software that you can publish documentation for these new features at the same time in sync using continuous integration and continuous delivery and fully automated. These are the links for all the tools that I showed you today. It's Ask a doctor to write the content. It's Antora to create a documentation site. It's the IntelliJ Ask a doc plugin to have a fully integrated experience inside your IDE. For those who want to integrate diagrams into their documentation, there's for example, plant URL. And if you want to integrate those into your documentation site, have a look at the Ask a doctor corky extension that also supports Antora. Thank you very much for your attention and I'm looking forward to your questions. Okay, so the question is, is it possible to replace syncs in restructured text and publication on read the docs with Ask a doc and Antora? Yeah, my answer to that would be yes. So with Antora, you would get like you would have on read the docs documentation where you can select a version, you can select a component and allow your users to hop between all these. Let's see if I, so this is for example, the Antora site. I can, now I'm within one component, I can choose what version I want to look at. And I can also down here, switch between the different components. There's the Antora and Antora default UI. Again, there's not a version checker here. That's very, very similar I would say to read the docs. Yeah, so this gives you this overview. One thing to keep in mind, I'm not sure how read the docs works, but Antora generates the full site in one go. So it pulls, if you have like one git repository with like one branch for each release, it will pull out all the branches at the same time. Great, one documentation site from that. I'm not sure how that works with other documentation tools, but that the way Antora does it and it has the benefit that you can really do great cross-references between versions if you want to do that. I hope that answers your question well. Yeah, and you say that you plan to publish on GitHub pages and yes, this is possible. You then have a GitHub action that creates the HTML and checks in that HTML to a separate branch in your repository. That's perfectly fine. Cool. Anyone have any more questions to Alexander? Okay, thank you again, Alexander. So this was the last session of this track. Yeah, please, sorry for interruption. No, it's your turn, I'm out.