WEBVTT 00:00.000 --> 00:10.480 So evolving real world, ask it out into a specification and how it will help you to 00:10.480 --> 00:11.480 system. 00:11.480 --> 00:15.840 Welcome to this talk here at the Tooled Docs Devroom at Firstum. 00:15.840 --> 00:20.760 My name is Alex and Ashrodes and I'm a principal soccer developer as a certain. 00:20.760 --> 00:27.780 At daytime I'm a kick-load developer in that spare time working in the Docs community 00:27.780 --> 00:30.780 mostly around ASCII doc. 00:30.780 --> 00:34.580 So this is the agenda for the next 20 something minutes. 00:34.580 --> 00:39.900 I talk about the motivation, why we write Docs and what tools do you want to use for that? 00:39.900 --> 00:44.460 A little bit of a workflow and how we want to connect all the things and automate all the 00:44.460 --> 00:48.980 things when it comes to documentation and then dive a bit deeper into the ASCII book 00:48.980 --> 00:52.700 brand of language documentation, something that the ASCII doc work in group has been working 00:52.700 --> 00:54.580 on over the past years. 00:55.580 --> 01:00.580 I'm happy to take questions also in the middle just raise a hand and I will ask you 01:00.580 --> 01:05.580 question, I will repeat it if I don't forget it and then we will have a more 01:05.580 --> 01:08.580 interactive session in this one. 01:08.580 --> 01:12.580 The mission is to get in the Docs out of the readers. 01:12.580 --> 01:16.580 Don't write them for ourselves. 01:16.580 --> 01:20.580 And that's a tool process happening to really get the Docs out. 01:20.580 --> 01:26.580 So you have authors that focus on the content, they focus on the structure, lots of typing 01:26.580 --> 01:30.580 involved but also a lot of more reading around involved here. 01:30.580 --> 01:35.580 And these authors then there's going to be a process that converts the documentation 01:35.580 --> 01:40.580 maybe to HTML, maybe to PDFs, maybe to online documentation system that you haven't 01:40.580 --> 01:41.580 placed. 01:41.580 --> 01:45.580 And then published the readers read it. 01:45.580 --> 01:49.580 You either want to educate the users, they want you want to provide them answers to 01:49.580 --> 01:50.580 their questions. 01:50.580 --> 01:55.580 These are the things about concepts and reference guides and how to all of that. 01:55.580 --> 02:00.580 You want to publish that and be read by people out there. 02:00.580 --> 02:05.580 And maybe artificial intelligence meets them as well. 02:05.580 --> 02:09.580 So yeah, this workflow about authoring, converting a publish. 02:09.580 --> 02:14.580 Let's dive a bit deeper into that and see what ASCII doc can do to that. 02:14.580 --> 02:19.580 And what ASCII doc actually is and never, I'm not going to use it in this talk yet. 02:19.580 --> 02:25.580 So when there are authors, they write some documentation, they validate, they changes. 02:25.580 --> 02:30.580 We, in long as talk, we saw how you can use command line tools for that to validate that. 02:30.580 --> 02:35.580 Maybe you even have a parser for either you or marked on a ASCII doc language. 02:35.580 --> 02:40.580 Other people review it, maybe you have automatic things like a veil to review it. 02:40.580 --> 02:43.580 And there's lots of tools that you can use for that. 02:43.580 --> 02:47.580 You maybe have a simple editor, maybe you have a full slash IDE. 02:47.580 --> 02:50.580 Maybe you have a browser, maybe you're command on interface. 02:50.580 --> 02:55.580 So all these things need to work together very, very well-form also. 02:55.580 --> 03:02.580 And it might end up on the language using and the tools are using how good they actually interact with each other. 03:02.580 --> 03:06.580 So I'm a, well, daytime developer. 03:07.580 --> 03:11.580 Documentary and at night. So, but this is an IntelliJ screenshot. 03:11.580 --> 03:15.580 And that's an IntelliJ IDE, which is an ASCII doc plugin installed. 03:15.580 --> 03:18.580 And as I said earlier, I have the maintain of the ASCII doc plugin. 03:18.580 --> 03:21.580 So I'm bragging about it, but hopefully not too much. 03:21.580 --> 03:25.580 So when you're writing an IDE, you will have a tree outline on the left. 03:25.580 --> 03:31.580 That will show you all the photos and files and you can browse through it. 03:31.580 --> 03:35.580 You will have an editor with some syntax highlighting here. 03:35.580 --> 03:39.580 And you will have some coloring, you will have you can fold things. 03:39.580 --> 03:43.580 It's hopefully working very nicely for you. 03:43.580 --> 03:48.580 And on the right, you have writing without a selection syntax highlighting on the completion. 03:48.580 --> 03:51.580 Yeah, grammar and check style. 03:51.580 --> 03:58.580 So you can really, if you miss a word and any of your sentence, it will point you with a little red line under it. 03:58.580 --> 04:01.580 You might have missing a word here. 04:01.580 --> 04:05.580 And for me being in order to make the thing you speak, that's very helpful. 04:05.580 --> 04:09.580 And on the right, you will see that usually a preview of the documentation you're currently writing. 04:09.580 --> 04:13.580 So, and this will never get together with a text that you're writing. 04:13.580 --> 04:21.580 You can also style the preview to that it really looks like the real websites. 04:21.580 --> 04:25.580 So the magic behind that is CSS. So if you have the CSS of your website, 04:25.580 --> 04:29.580 you can also use the same CSS to style your preview in your IDE. 04:29.580 --> 04:32.580 So it can get as nice as that. 04:32.580 --> 04:34.580 Then you have a version control. 04:34.580 --> 04:40.580 When you are into documentation as code, you can really collaborate with all the other people in the project. 04:40.580 --> 04:43.580 With other people writing documentation, with other people writing code. 04:43.580 --> 04:51.580 And ask them maybe to review something you've read written, or have them, or maybe really write what they have written. 04:51.580 --> 04:57.580 So, yeah, and this is then what, well, maybe good time for this or so. 04:57.580 --> 04:59.580 So demo, maybe I have the time. 04:59.580 --> 05:03.580 So this is the Askidok plugin for untaligery. 05:03.580 --> 05:06.580 It's our project. So we eat our own dog food. 05:06.580 --> 05:09.580 So we are writing our documentation in Askidok. 05:09.580 --> 05:13.580 So I can go through here. I can do some folding. 05:13.580 --> 05:16.580 I can do everything you would usually do with code. 05:16.580 --> 05:19.580 I can jump from one page to another. 05:19.580 --> 05:23.580 I go here and it will then update the preview. 05:23.580 --> 05:25.580 The update, I have images here. 05:25.580 --> 05:29.580 When I click on the preview, the editor will jump to the right line. 05:29.580 --> 05:36.580 So it's, yeah, it's a full slash IDE to writing to write documentation as code with Askidok. 05:36.580 --> 05:42.580 On the other side, I also know that might be a bit overwhelming. 05:42.580 --> 05:48.580 People might want to use tools that are smaller with less functionality. 05:48.580 --> 05:52.580 And that's not so overwhelming, but that's a choice that you have. 05:52.580 --> 05:55.580 Okay, but that's like the full slash IDE. 05:55.580 --> 05:59.580 And when I build this tool on the right here to generate this preview, 05:59.580 --> 06:05.580 I was integrating Askidok being the tool that can run the Askidok to HTML. 06:05.580 --> 06:10.580 On the left, I was set up with the task and the challenge to do an Askidok parser. 06:10.580 --> 06:16.580 To do the highlighting of the syntax, to do the folding, to do the all the completion, 06:16.580 --> 06:19.580 all that. I needed to write that on my own, 06:19.580 --> 06:25.580 or enhance what others have been writing before me when I took over the plugin as a maintainer. 06:25.580 --> 06:30.580 And so yeah, so we have kind of two implementations from Askidok, 06:30.580 --> 06:34.580 one implementation that works for syntax highlighting and all the completion 06:34.580 --> 06:37.580 and other implementations here that bring away the preview. 06:37.580 --> 06:44.580 And in an ideal world, they will both do the same, right, and behave the same. 06:44.580 --> 06:48.580 And this is then how Askidok works like. 06:48.580 --> 06:53.580 So you start with a simple text. You have like each sentence of a separate line, 06:53.580 --> 06:55.580 every blank line, create a new paragraph. 06:55.580 --> 06:59.580 You can do styling of words in here, you can do lists. 06:59.580 --> 07:02.580 You can there are numbers and unnumbered. 07:02.580 --> 07:05.580 Of course, when you put a number to list, you wouldn't put the numbers in here 07:05.580 --> 07:08.580 because well, it's numbered, it's eventually anyway. 07:08.580 --> 07:10.580 So you can skip that. 07:11.580 --> 07:14.580 And you also do the admonition stuff, 07:14.580 --> 07:16.580 like something is important. 07:16.580 --> 07:19.580 Once some tips here, you want to have an example. 07:19.580 --> 07:21.580 And depending on the outline, 07:21.580 --> 07:24.580 it will always be the same like on the left and askidok. 07:24.580 --> 07:26.580 But then you render it using a star, 07:26.580 --> 07:27.580 and then add a star sheet to it, 07:27.580 --> 07:30.580 and this is one of the default stars sheet of intolerers. 07:30.580 --> 07:33.580 It will look like this in an ice wing. 07:33.580 --> 07:35.580 You can also do tables. 07:35.580 --> 07:39.580 You can do simple tables, or you can do tables with all the things 07:39.580 --> 07:40.580 that you usually need. 07:40.580 --> 07:43.580 You want to have them right aligned, left aligned. 07:43.580 --> 07:46.580 Top button, callspan, rowspan, what not. 07:46.580 --> 07:48.580 All that is part of the Askidok syntax. 07:48.580 --> 07:50.580 It's still plain text on the left, 07:50.580 --> 07:52.580 that you can put in a git repository and 07:52.580 --> 07:54.580 diff and see who changed what. 07:54.580 --> 07:57.580 An unerightable, give you a nice table. 07:57.580 --> 08:00.580 You can also embed source codes. 08:00.580 --> 08:03.580 For example, earlier we can put it in line, 08:03.580 --> 08:05.580 but it's even better, in my point of view, 08:05.580 --> 08:07.580 to put it in the next tunnel file. 08:07.580 --> 08:10.580 Maybe even you can reference in your examples, 08:10.580 --> 08:14.580 the file that is in your real code base, 08:14.580 --> 08:16.580 that it's in test-it using CICD, 08:16.580 --> 08:19.580 or maybe in your test cases. 08:19.580 --> 08:23.580 Right examples, you put examples in the folder, 08:23.580 --> 08:25.580 where you can run some tests on them, 08:25.580 --> 08:27.580 and then you suddenly end up with a documentation 08:27.580 --> 08:29.580 that has code samples that compile, 08:29.580 --> 08:31.580 and even do the right thing because they're tested. 08:31.580 --> 08:34.580 So that's, I think, pretty awesome. 08:34.580 --> 08:37.580 So the simplest way is to put some comments, 08:37.580 --> 08:40.580 like if you can include the files as I've done it here, 08:40.580 --> 08:42.580 and then you have some text. 08:42.580 --> 08:45.580 If you really want to have only this special line here, 08:45.580 --> 08:48.580 and you see this, 08:48.580 --> 08:53.580 this tag equals SOP, this end repeated here, 08:53.580 --> 08:56.580 and then it extracts only this one line here, 08:56.580 --> 08:58.580 and prints and only this one line here, 08:58.580 --> 09:00.580 and also congrats this comment here, 09:00.580 --> 09:03.580 because the one, two, this one at the end, 09:03.580 --> 09:05.580 showing that it is a call out. 09:05.580 --> 09:09.580 So basically, if you have a border book from a Riley, 09:09.580 --> 09:12.580 which has some nice code examples, 09:12.580 --> 09:13.580 call out what not. 09:13.580 --> 09:16.580 All these starting can be done using Askidok, 09:16.580 --> 09:19.580 and create a great documentation experience 09:19.580 --> 09:22.580 for those using the documentation of your product. 09:22.580 --> 09:26.580 So we had about Vale before, 09:26.580 --> 09:29.580 and you can use also Vale to validate Askidok, 09:30.580 --> 09:32.580 there's a red head style. 09:32.580 --> 09:34.580 I can import here, I'll say goodwill, 09:34.580 --> 09:35.580 maybe some of the start here, 09:35.580 --> 09:38.580 and then finally point it to some Askidok content, 09:38.580 --> 09:41.580 and it will show me some warnings. 09:41.580 --> 09:44.580 For example, if I integrate everything into a Valexon, 09:44.580 --> 09:46.580 with a Rata AI, 09:48.580 --> 09:52.580 and then put that into my GitHub pull request checks, 09:52.580 --> 09:55.580 it will also annotate my pull request and GitHub. 09:55.580 --> 09:57.580 But behind the scenes, it's again, 09:57.580 --> 10:00.580 somebody is pausing Askidok to make sense 10:00.580 --> 10:02.580 out of what I've written here, 10:02.580 --> 10:04.580 getting out all the syntax in here, 10:04.580 --> 10:06.580 and getting it black to the plain text, 10:06.580 --> 10:09.580 and then the plain text is piped into 10:09.580 --> 10:11.580 Vale to make sense out of it. 10:11.580 --> 10:13.580 Again, somebody pausing Askidok, 10:13.580 --> 10:17.580 I think the Vale is using first a conversion from Askidok to HTML, 10:17.580 --> 10:19.580 and then looking at the HTML, 10:19.580 --> 10:22.580 and referencing back from snippets in the HTML, 10:22.580 --> 10:24.580 which line of source code is being used. 10:24.580 --> 10:26.580 Like there's a debug mode in Askidok, 10:26.580 --> 10:28.580 you can tell Askidok to put some additional notes 10:28.580 --> 10:30.580 on the HTML to reference source lines 10:30.580 --> 10:32.580 in the original Askidok. 10:32.580 --> 10:34.580 So yeah, cool stuff, but then, 10:34.580 --> 10:36.580 how to parse Askidok. 10:36.580 --> 10:40.580 Everybody seems to have the same strategy. 10:40.580 --> 10:43.580 Vale comes to conversion, 10:43.580 --> 10:46.580 I don't know, so yeah, to actually people to read it. 10:46.580 --> 10:50.580 Then you have HTML, dogbook, PDF format, 10:50.580 --> 10:52.580 e-pop, lots of formats to convert to. 10:52.580 --> 10:54.580 You have lots of tools you want to use, 10:54.580 --> 10:57.580 maybe even NPM, CLI tools, 10:57.580 --> 11:00.580 and here are different implementations of the Askidok language, 11:00.580 --> 11:02.580 that all we'd askidok, 11:02.580 --> 11:04.580 and they produce different outputs, 11:04.580 --> 11:06.580 and they run on different run times. 11:06.580 --> 11:09.580 For example, the Askidok project runs on Ruby, 11:09.580 --> 11:11.580 JavaScript, and Java run times, 11:11.580 --> 11:14.580 so we can really integrate it into your software projects, 11:14.580 --> 11:17.580 maybe to publish documentation, 11:17.580 --> 11:21.580 we are inside your application that you also publish. 11:21.580 --> 11:23.580 There's a go implementation, 11:23.580 --> 11:26.580 that's very distinct from the Askidok implementation, 11:26.580 --> 11:28.580 there's an Haskell implementation. 11:28.580 --> 11:30.580 So again, but as an also, 11:30.580 --> 11:33.580 you want to really write your Askidok content once, 11:33.580 --> 11:36.580 and independent of the tool, 11:36.580 --> 11:39.580 it should at least make the same sense out of the structure 11:39.580 --> 11:42.580 that you written, like all the equals signs for the heading, 11:42.580 --> 11:45.580 all the example blocks they should all be parsed by the same way. 11:45.580 --> 11:48.580 And if all the tools parsed in the same way, 11:49.580 --> 11:51.580 you will have a good authoring experience. 11:51.580 --> 11:55.580 Today, it's working already quite well, 11:55.580 --> 11:58.580 but as of today, there's no official specification yet, 11:58.580 --> 12:01.580 and we're working on that. 12:01.580 --> 12:06.580 So then, how do I use them command line converters, 12:06.580 --> 12:07.580 or embedding things? 12:07.580 --> 12:12.580 So command line could be the Askidok implementation. 12:12.580 --> 12:14.580 The Askidok implementation, 12:14.580 --> 12:16.580 you pass it a file on the command line, 12:16.580 --> 12:18.580 and then it will create, by default, 12:18.580 --> 12:20.580 HTML from the Askidok. 12:20.580 --> 12:21.580 And when you do some, 12:21.580 --> 12:23.580 maybe suspicious things in there, 12:23.580 --> 12:24.580 it will give you warnings. 12:24.580 --> 12:26.580 For example, online two, 12:26.580 --> 12:28.580 multiple IDs detected in style attribute. 12:28.580 --> 12:29.580 So yeah, that's, 12:29.580 --> 12:32.580 means something is maybe not so self-explanatory, 12:32.580 --> 12:35.580 but you will go to line two and figure out 12:35.580 --> 12:37.580 what it's complaining about. 12:37.580 --> 12:39.580 So the good tool will give you warnings, 12:39.580 --> 12:41.580 and these warnings will be parsables, 12:41.580 --> 12:43.580 so that the tool and editor, for example, 12:43.580 --> 12:45.580 could point you directly to line two, 12:45.580 --> 12:48.580 when it runs this tool, maybe in the background. 12:48.580 --> 12:50.580 Maybe I hear somebody saying, 12:50.580 --> 12:52.580 maybe it should be JSON the output, 12:52.580 --> 12:55.580 but, okay. 12:55.580 --> 12:57.580 At the same question, 12:57.580 --> 12:58.580 yeah. 12:58.580 --> 13:00.580 When you have multiple source files, 13:00.580 --> 13:03.580 you can change all the files in duty to include. 13:03.580 --> 13:05.580 How can you make sense on the line that, 13:05.580 --> 13:06.580 for sure, is that? 13:06.580 --> 13:07.580 Yeah, so the question was, 13:07.580 --> 13:09.580 when I use lots of includes, 13:09.580 --> 13:11.580 how can I make sense out of the line? 13:11.580 --> 13:14.580 It will print the name of the file there as well. 13:14.580 --> 13:16.580 So it will not be the file that you pass on the command line, 13:16.580 --> 13:19.580 but it will be the file that you ended up by the include. 13:19.580 --> 13:21.580 So the final file you're in. 13:21.580 --> 13:25.580 It wouldn't give you a recursive stack of all the files 13:25.580 --> 13:26.580 how you got there, 13:26.580 --> 13:28.580 but it will tell you in this file, 13:28.580 --> 13:32.580 after that many includes steps on that line, 13:32.580 --> 13:33.580 is the problem. 13:33.580 --> 13:38.580 So, yeah, that would hopefully help a bit at least. 13:39.580 --> 13:40.580 Right. 13:40.580 --> 13:42.580 Actually, when I, 13:42.580 --> 13:44.580 the IntelliJ plugin for, 13:44.580 --> 13:46.580 sorry, the ASCII doc plugin for IntelliJ, 13:46.580 --> 13:48.580 runs ASCII doctor in the background 13:48.580 --> 13:50.580 to do this validation, 13:50.580 --> 13:52.580 and there's a hooking mechanism there. 13:52.580 --> 13:54.580 I can get all these warnings in errors. 13:54.580 --> 13:58.580 So I can mark both in the problem list of the project, 13:58.580 --> 14:00.580 and in the problem of the file, 14:00.580 --> 14:02.580 or some weekly lines. 14:02.580 --> 14:04.580 So you can really have the highlighting at the right place, 14:04.580 --> 14:06.580 so that's possible there. 14:07.580 --> 14:09.580 And if there's an include, 14:09.580 --> 14:12.580 I'm also showing that this include leads to that problem, 14:12.580 --> 14:15.580 so the idea can do that. 14:15.580 --> 14:16.580 What I'm showing here, 14:16.580 --> 14:17.580 as a second example, 14:17.580 --> 14:19.580 is how we are, 14:19.580 --> 14:22.580 if you go to the ASCII doc or website, 14:22.580 --> 14:25.580 there's an embedded editor on the website, 14:25.580 --> 14:28.580 like a minimal editor based on JavaScript. 14:28.580 --> 14:30.580 When you type something on the left, 14:30.580 --> 14:32.580 it will render a preview on the right. 14:32.580 --> 14:34.580 It's 100% JavaScript. 14:34.580 --> 14:35.580 It runs in your browser. 14:35.580 --> 14:39.580 It doesn't do any communication with the backend here. 14:39.580 --> 14:42.580 That makes it both very fast, 14:42.580 --> 14:47.580 and very responsive for your ID. 14:47.580 --> 14:50.580 So a lot of ways to embed it. 14:50.580 --> 14:54.580 And then you can also write extensions for it. 14:54.580 --> 14:56.580 Well, extend and occur on the specific, 14:56.580 --> 14:58.580 specific to an implementation, 14:58.580 --> 15:00.580 but you can write, for example, 15:00.580 --> 15:01.580 for the ASCII doc implementation, 15:01.580 --> 15:03.580 you can write an extended, 15:03.580 --> 15:05.580 extend the ASCII doc syntax, 15:05.580 --> 15:07.580 it interacts on the AST level, 15:07.580 --> 15:11.580 so you can manipulate the text that you've been writing 15:11.580 --> 15:13.580 in a way while you are converting it, 15:13.580 --> 15:15.580 like creating one piece of ASCII doc, 15:15.580 --> 15:17.580 mixing a ground, 15:17.580 --> 15:18.580 augmentating it, 15:18.580 --> 15:20.580 removing stuff, 15:20.580 --> 15:23.580 to a new version of ASCII doc in this is then converted. 15:23.580 --> 15:28.580 This makes it possible that you write an extension, 15:28.580 --> 15:31.580 and the extension does not need to care about the output format, 15:31.580 --> 15:33.580 because it's only changing the AST, 15:33.580 --> 15:35.580 only changing the ASCII doc, 15:35.580 --> 15:37.580 and the output will be reflected 15:37.580 --> 15:41.580 in both the HTML and PDF and whatnot output format. 15:41.580 --> 15:43.580 You can then publish it in the end, 15:43.580 --> 15:45.580 so you can use a static site publisher, 15:45.580 --> 15:47.580 like Hugo, and Torra, 15:47.580 --> 15:49.580 drape, etc. 15:49.580 --> 15:51.580 and for example, 15:51.580 --> 15:53.580 and Torra being one of those that really special, 15:53.580 --> 15:55.580 while the others are 15:55.580 --> 15:57.580 to a lot of market languages, 15:57.580 --> 15:59.580 and ASCII doc, 15:59.580 --> 16:03.580 and comes with a very good opinionated way to do it, 16:03.580 --> 16:07.580 so we're now looking here at the Torra documentation, 16:07.580 --> 16:09.580 written in ASCII doc, 16:09.580 --> 16:11.580 published by Antora, 16:11.580 --> 16:13.580 so it gives you things like 16:13.580 --> 16:15.580 site publishing, 16:15.580 --> 16:17.580 an outline, 16:17.580 --> 16:19.580 navigation outline on the left, 16:19.580 --> 16:20.580 on the top, 16:20.580 --> 16:21.580 linking, 16:21.580 --> 16:23.580 customizable, 16:23.580 --> 16:25.580 themes, sites search, 16:25.580 --> 16:27.580 and also an outline of the page, 16:27.580 --> 16:29.580 linking redirects for page it has been named, 16:29.580 --> 16:31.580 so it's not a content management system, 16:31.580 --> 16:33.580 and it's true quite a sense, 16:33.580 --> 16:35.580 but has a lot of features on that. 16:35.580 --> 16:37.580 If you want to set up such 16:37.580 --> 16:39.580 two, like Antora, 16:39.580 --> 16:41.580 a little brief intro here, 16:41.580 --> 16:43.580 so we need to also that 16:43.580 --> 16:45.580 or some also set creative content in the 16:45.580 --> 16:47.580 Wider Find structure, 16:47.580 --> 16:49.580 it comes out with an outline like this, 16:49.580 --> 16:50.580 or each component, 16:50.580 --> 16:51.580 you will have any component, 16:51.580 --> 16:52.580 you will have modules, 16:52.580 --> 16:53.580 you will have folders for attachments, 16:53.580 --> 16:55.580 examples, images, 16:55.580 --> 16:57.580 so this is a very recurring structure, 16:57.580 --> 16:59.580 and the good thing is when you work in one 16:59.580 --> 17:01.580 Antora project and learn about 17:01.580 --> 17:05.580 this structure will be the same in any other project, 17:05.580 --> 17:06.580 that uses Antora, 17:06.580 --> 17:09.580 if you, for example, go to other static site publishers, 17:09.580 --> 17:11.580 for example, 17:11.580 --> 17:13.580 if you go, so then it really depends on the theme, 17:13.580 --> 17:14.580 where you put the files, 17:14.580 --> 17:15.580 and it's very custom, 17:15.580 --> 17:16.580 this Antora, 17:16.580 --> 17:19.580 it's, I'd say, opinionated in a positive way. 17:20.580 --> 17:21.580 Yeah. 17:27.580 --> 17:29.580 Yeah, well, that's not the obvious. 17:29.580 --> 17:32.580 Well, it's not supported by Antora by itself, 17:32.580 --> 17:34.580 you would then take this structure, 17:34.580 --> 17:36.580 maybe you have a translation memory 17:36.580 --> 17:38.580 and replicate it to a structure 17:38.580 --> 17:40.580 that has maybe the module name 17:40.580 --> 17:41.580 with a language at the end, 17:41.580 --> 17:43.580 and then generate that, 17:43.580 --> 17:46.580 and then in people can switch between the two languages, 17:46.580 --> 17:48.580 but the different languages. 17:48.580 --> 17:52.580 So, but it's not built into Antora itself. 17:52.580 --> 17:55.580 But then need to have a person who would make sure 17:55.580 --> 17:57.580 that all the automation scripts and validation 17:57.580 --> 17:58.580 and publishing works, 17:58.580 --> 18:00.580 that the second role in the third 18:00.580 --> 18:03.580 will be somebody who customizes your theme. 18:03.580 --> 18:05.580 So getting your talks out to the readers, 18:05.580 --> 18:07.580 so we've seen a lot of tools working together 18:07.580 --> 18:10.580 to make it work for authors, for the conversion process 18:10.580 --> 18:11.580 and publishing, 18:11.580 --> 18:14.580 and what the ASCII doc working group 18:14.580 --> 18:16.580 at the Eclipse Foundation has done, 18:17.580 --> 18:20.580 we first worked on establishing the brand 18:20.580 --> 18:21.580 and the language documentation, 18:21.580 --> 18:23.580 so we can read up on this. 18:23.580 --> 18:25.580 So that's why you see this in R and the TM here. 18:25.580 --> 18:27.580 So it's now owned by the Eclipse Foundation 18:27.580 --> 18:30.580 to make sure that it's really that brand. 18:30.580 --> 18:32.580 It comes with our distinct CR, 18:32.580 --> 18:34.580 recognizable brand and stickers, 18:34.580 --> 18:39.580 and stickers are at the table at the right front there. 18:39.580 --> 18:42.580 So you can read up on the guidelines here. 18:42.580 --> 18:44.580 There's also a web page, 18:44.580 --> 18:46.580 if you go to ASCII doc.org. 18:46.580 --> 18:50.580 You will get an intro similar to the talk this. 18:50.580 --> 18:52.580 I'm presenting here today. 18:52.580 --> 18:55.580 You will also see a screen shot of an IDE. 18:55.580 --> 18:57.580 IntelliJ, with the ASCII doc plugin, 18:57.580 --> 18:59.580 showing the ASCII doc documentation. 18:59.580 --> 19:02.580 It's really an inception moment, if you go there. 19:02.580 --> 19:06.580 We worked on the ASCII doc language documentation 19:06.580 --> 19:08.580 that's been written for users 19:08.580 --> 19:10.580 and human users, as I say. 19:10.580 --> 19:12.580 So originally, there were 19:13.580 --> 19:16.580 it has its root in the ASCII doc community, 19:16.580 --> 19:19.580 and the ASCII doc community was writing documentation 19:19.580 --> 19:21.580 to document ASCII doc. 19:21.580 --> 19:25.580 But now it's separated the tool from the language. 19:25.580 --> 19:28.580 So this is now the documentation about the ASCII doc language, 19:28.580 --> 19:30.580 telling you everything you need to know, 19:30.580 --> 19:32.580 in a very detailed format, 19:32.580 --> 19:34.580 more like a reference documentation, 19:34.580 --> 19:35.580 saying how to do headers, 19:35.580 --> 19:37.580 how to document types, 19:37.580 --> 19:39.580 section paragraphs, how that all works, 19:39.580 --> 19:41.580 to indicate humans to do that. 19:41.580 --> 19:44.580 But then it's, 19:44.580 --> 19:46.580 with all the tools I've shown earlier, 19:46.580 --> 19:48.580 it's not enough to make it just work for humans. 19:48.580 --> 19:50.580 You need to also make it work for the tools 19:50.580 --> 19:52.580 to do the posing right. 19:52.580 --> 19:54.580 And this is now where the current work 19:54.580 --> 19:58.580 is going into the ASCII doc language specification. 19:58.580 --> 20:01.580 It's again hosted at the ASCII Foundation. 20:01.580 --> 20:03.580 We have several people contributing there, 20:03.580 --> 20:06.580 and we'd be loved to have more people in here. 20:06.580 --> 20:08.580 So it comes with the specification 20:08.580 --> 20:11.580 as in the ASCII doc language program. 20:11.580 --> 20:15.580 Well, one is then documentation writing it 20:15.580 --> 20:18.580 in a way that it's a specification 20:18.580 --> 20:22.580 that can be read and implemented by two developers. 20:22.580 --> 20:24.580 So as I said earlier, 20:24.580 --> 20:26.580 we want everybody to ask it on the same way, 20:26.580 --> 20:29.580 and if everybody process ASCII doc in the same way, 20:29.580 --> 20:31.580 we will have a great user experience here. 20:31.580 --> 20:36.580 It's the time of the future to move the kind of user language usage 20:36.580 --> 20:39.580 into the ASCII doc section, 20:39.580 --> 20:43.580 rather than just on the ASCII doc doc, what they can do. 20:43.580 --> 20:45.580 It's a bit confusing out there. 20:45.580 --> 20:47.580 What makes with the implementation order? 20:47.580 --> 20:51.580 Yeah, so I'd say ASCII doc there is a big part of the ecosystem, 20:51.580 --> 20:53.580 so it's still a good place to be. 20:53.580 --> 20:55.580 Maybe it will move to another place eventually. 20:55.580 --> 20:57.580 That's a good point. 20:57.580 --> 20:58.580 I can take that with me. 20:58.580 --> 21:00.580 But that's occurring not a plan for that one. 21:00.580 --> 21:02.580 Yeah. 21:02.580 --> 21:06.580 And then with each good language specification, 21:06.580 --> 21:10.580 it comes also a technical compatibility kit. 21:10.580 --> 21:14.580 So the technology compatibility kit is basically test cases. 21:14.580 --> 21:17.580 So, well, first, well, 21:17.580 --> 21:19.580 let's start with a language specification first. 21:19.580 --> 21:22.580 We have, well, 21:22.580 --> 21:25.580 specification decision records here, 21:25.580 --> 21:27.580 describing one problem at a time, 21:27.580 --> 21:29.580 getting all the input from the community, 21:29.580 --> 21:33.580 defining things in the way that we will not break existing ASCII doc documentation out there. 21:33.580 --> 21:37.580 So all the documentation that has been written for the last 10, 21:37.580 --> 21:38.580 something years. 21:38.580 --> 21:39.580 We don't want to break that, 21:39.580 --> 21:44.580 but we want to capture really the best practices of how to do it in this specification. 21:44.580 --> 21:48.580 And we have to discussion on going on the zoolip set there. 21:48.580 --> 21:50.580 And once we come up with, 21:50.580 --> 21:52.580 this is how it should look like. 21:52.580 --> 21:54.580 We come up also up with, 21:54.580 --> 21:55.580 sorry, 21:55.580 --> 21:56.580 a bit too much taking, 21:56.580 --> 22:01.580 with a TCK to show how it should be parts from different implementations. 22:01.580 --> 22:02.580 Like, 22:02.580 --> 22:06.580 and this can be used by either the tool that's wanted to do some, 22:06.580 --> 22:08.580 some sanity checking on the ASCII doc, 22:08.580 --> 22:12.580 it can be used by the tool that wants to show syntax highlighting any data, 22:12.580 --> 22:16.580 or it can be used by the tool that wants to convert ASCII doc to HTML, 22:16.580 --> 22:18.580 or maybe the new form of it comes up soon. 22:18.580 --> 22:21.580 So this is the most snippet of ASCII doc content here on the left, 22:21.580 --> 22:23.580 saying it was a title and a body, 22:23.580 --> 22:27.580 and I've been a lengthy JSON that I needed to cut a bit short here. 22:27.580 --> 22:29.580 But it really shows on, 22:29.580 --> 22:33.580 this is how it should look like as a grammar, right? 22:33.580 --> 22:35.580 This is how, like, 22:35.580 --> 22:39.580 locations of different columns and lines and bad styles, 22:39.580 --> 22:43.580 and so we're trying to make it really, 22:43.580 --> 22:45.580 really simple or, 22:45.580 --> 22:46.580 well, 22:46.580 --> 22:47.580 it's not simple to do all the patrol, 22:47.580 --> 22:49.580 but then at least simple to test it, 22:49.580 --> 22:53.580 have some references to go against and test cases for those two militaries. 22:57.580 --> 22:59.580 So this is, by the end of the talk, 22:59.580 --> 23:01.580 so I talked about ASCII doc, 23:01.580 --> 23:03.580 I talked about ASCII doc, 23:03.580 --> 23:05.580 the world implementations, 23:05.580 --> 23:06.580 the entity, 23:06.580 --> 23:07.580 ASCII doc plugin, 23:07.580 --> 23:09.580 and Torah, 23:09.580 --> 23:11.580 and lots of other videos. 23:11.580 --> 23:15.580 And the slides you see here today are here behind this QR code. 23:15.580 --> 23:17.580 There's also, 23:17.580 --> 23:18.580 well, 23:18.580 --> 23:19.580 I think we heard, 23:19.580 --> 23:20.580 in the previous talk, 23:20.580 --> 23:24.580 they were talking about how to document something with somebody who was writing a tool. 23:24.580 --> 23:27.580 This is what I try to do in this technical writing. 23:27.580 --> 23:29.580 Here, if you enter this page, 23:29.580 --> 23:31.580 you will count to, 23:31.580 --> 23:32.580 a 12-step guide, 23:32.580 --> 23:34.580 how to set up an territory, 23:34.580 --> 23:37.580 as a technical writer who might not yet know about the territory, 23:37.580 --> 23:39.580 starting with how to install it, 23:39.580 --> 23:41.580 how to install the right plugins, 23:41.580 --> 23:44.580 how to get familiar with ASCII doc, 23:44.580 --> 23:46.580 how to customize your project 23:46.580 --> 23:48.580 you have a good code of experience, 23:48.580 --> 23:49.580 a code of work with others. 23:49.580 --> 23:52.580 So, all the content is free online, 23:52.580 --> 23:54.580 and please contribute. 23:54.580 --> 23:56.580 I also recorded like 60 minutes video, 23:56.580 --> 23:58.580 which are on Udemy. 23:58.580 --> 24:01.580 So, if you want to get a free ticket on that, 24:01.580 --> 24:03.580 just let me know. 24:03.580 --> 24:04.580 So, that's it. 24:04.580 --> 24:05.580 Thanks a lot. 24:05.580 --> 24:08.580 Thank you.