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