Okay. Well, cool.
Yeah. So, displayed at her.
I like usually like a standing and jumping around,
but here I've got to type.
So, you forgive me for sitting down here.
So, we'll talk about
embeddable code playground specifically in a dogs.
Let me ask how many of you
prefer dull static dogs compared to interactive dogs?
Because you probably have to maintain them.
Oh, okay.
Okay. I thought you are writing dogs.
Yeah. Well, understood.
Well, so, just to know who I'm,
Peter Seitz, Anton is actually
the author of the code we'll talk about,
but unfortunately, he couldn't get a visa to come here.
So, you stuck with me.
But if you have any like a super advanced questions,
there is Anton contacts and you can
send it to him, he's very responsive guy.
So, if you think about
their more interactive,
well, code playground,
interactive scenarios, they generally better work
for the explain the topics and also allowing to engage the reader.
Maybe not all the readers,
but I think the best ones,
the most curious ones,
which actually want to understand how things work.
So, we'll look at three items in this short presentation.
Their use cases, their approach,
what we have in this open source project,
and implementation.
First, let's look at their tutorials.
If you look at the tutorials,
you often want to explain something by example.
I think we can look at this very,
let's say simple case,
we are actually using some real live or the SAS out there,
which is provides a very simple database where we can
push some simple JSON object.
We can go ahead and run it.
Actually, what happens in this case,
well, it does interaction as described above.
Then sends their object to the database.
Well, what we can also do is to go ahead and
go ahead and to modify that and run.
Then we can see this object was stored.
Now, we want to demo the Cloud API.
In this case, to play with it,
we can go ahead and also use the get one to play with it somewhere.
Let's say you have a second message and we have,
and if you can say,
is there like some message number 45?
We can see, well, it's not there.
Again, if you really want to experiment and play what works
and how it works,
that can be the very beautiful way to do it.
Another cool way what we found it's being used
is their release nodes.
What we have in this case is this example.
If you look at the Golang,
they have just made recently very important changes,
how the variables operate as related to coroutines.
If you look in this case,
that makes it look like a little bit counter-intuitive.
We have coroutines called in the loop,
and for some reason they are not showing different loop counters.
Well, in Golang 1.22, that was fixed.
If you guys want to showcase their feature in the release
don and the commentations,
but really let people to explore and put the holes,
in this case I think that's a wonderful tool.
I'm not sure about you,
I often then read in some features,
I do a lot of work with databases,
and they say, hey, we implemented that new feature,
and I wanted to put a hole,
oh, did you implement that option,
or does it work in this way?
That is a very easy way to play with it
if I would go in through with all their installation process,
and so on and so forth.
Another example we can see is some of their describing,
some of their options in a documentation.
Like if you think in this case as a corral,
everybody could use corral,
it has this wonderful JSON options,
with this very cool, correct,
but also very mouthful example,
which we can also go ahead and provide example for.
Say, hey, that is a JSON object,
we post that to the server,
that is what we get in return.
This HTTP bin, that is actually another like
well-known open source project,
which essentially allows you to post something to that
and then get in return,
what exactly you posted with Othead,
and so on and so forth,
very convenient for debugging.
What you can also do here in this case,
if you are curious to say, well, interesting.
So, corral has the support for JSON.
Does it validates JSON,
or just sends whatever stuff we have?
Well, let's check it out.
Well, we can see in this case,
we are getting the error response back from the server,
rather some sort of corral output,
that means it doesn't.
Again, that can be very helpful to get the user to explore
kind of what he's not very certain,
which may not be quite explained
in this portion of documentation.
Or we can also showcase example,
what existed in the docs,
how we can send the output from file.
Pretty simple here.
Okay. If you are looking at the deep dives,
there may be some interesting in terms of more functionality.
Going to a database,
space where I spent a lot of my time,
let's say we want to describe what is an absurd in SQL.
All right, anybody heard what is absurd?
Right, well, that is something like,
we want to insert the data,
but if it's out there, we want to update it.
The very common.
Okay, so we want to say,
let's say we have this table out there, right?
And we want to go ahead and use their MySQL insert or replace
syntax, right?
Then we want to, well, as I said,
like to update one employee's salary and then also add another
one, well, we can go ahead and run it.
Like why use this as example here?
Because what you can see is we are not showing everything in
example, right?
We are working with some sort of like a seed data which is,
well, was pre-created as a part of a previous scenario, right?
Which is very common.
Here is also another example of the same thing,
but with Postgres, right?
Where we're using a different scenario, right?
And you may ask, well, okay, this is how it works,
but I know also the Postgres SQL has a syntax on conflict
do nothing, right?
So what would that be if that's what we do?
Oh, well, in this case, we can see what the Emma's salary, right?
Which was a conflict in row, was not changed.
So again, we can play with those things.
Okay, well, these are kind of setting landscape, I think,
what things can be useful, but now let's look in terms of what
is approach and how it works.
Now, if you think about the tools and the doc creation, right?
You would find what it is not easy to find the good
technical writers, right?
Or documentation offers, right?
And they also can be rather, well, let's go like a selfish
of a time, right?
They don't want to do a lot of useless crap, right?
In this case.
So we want to make sure that writer experience is important,
not just the reader experience, which we already defined,
has one of those interactive playgrounds.
So what approach we took in this project is saying how we can
make it as sort of like a seamless as possible, right?
We don't want to say, hey, you know what, you are going to create
our interactive code playground in completely different tooling,
right, separate from documentation, right?
And then figure out is that going to live in the same version
control, right, and so on and so forth, right?
Or, you know, things like that.
What we want in this case is to have your documentation, right,
which was this, right?
Just as easy as possible, add the ability to run and to edit
and run, right?
So you can say, hey, we added, you can see the run and edit here.
And if I run, you can see what is the output of that
documentation example is.
So how can we approach that?
So it is easy or integration which is easy on writing.
Well, it's actually quite easy.
So what we have is you are writing documentation in the same
format as you got used to, right?
Let's say maybe it's a markup language, as in this example,
or something else.
And then you can embed this like a code API widget.
That widget itself will figure out the previous code block
and make it interactive, right?
So there is no, like, some special thing required,
and that pretty much works in any documentation thing
which already exists, right?
So you can see that example here.
So the code which existed here just gets interactive.
So, well, of course, hello world is always easier, right?
Let's look at some more complicated examples.
One, I think, which is very important is the template
approach, right?
I think what I briefly mentioned already,
if I want to show something like this, right?
That is like a relatively, you know, complicated query, right?
For that to be meaningful, I also need to pre-generate table
in this case, which I probably do not want to have
on my documentation thing.
And this is designed done by providing a template.
So a template in this case is basically something which is
run before the scenario is done, right?
And in this case, I can write some text and, hey,
I created a table, but I'm not really specifically
final comments because there's a irrelevant in this case.
I populated with some data and then I have a code,
the code which was created before, right?
That is how template would look like.
So I can highlight, right, where exactly in the context,
I want to run that code which was,
which is interactive part of the documentation.
Okay, so here is another thing which you will find quite helpful.
So if you are building some sort of tutorial, right,
building the tutorial, right, you would often want to say,
hey, there is actually multiple steps where I need the user
to go through them one after another.
And that is an example here.
What you can see is what we are defining the function
in a one-code block and then we are using that function
in a in a another code block, right?
We can, and I'll show you in a second, define dependency
between those code blocks.
That means when you are running this second section,
the first section would always be run,
like let me, I don't know, let's say break this code, right?
For example, and then I can go ahead and run the second one.
It says, oh, well, you know, things got broken, right,
on the previous stuff, right?
And how that works is what we identify,
we refer to the first one as a cell number two, right?
And then identify the second snippet as a cell
which depends on a cell number two, right?
That means pretty much that the content of that cell
is going to be run.
Then the second cell is run, right?
Even if you, as users, don't click run, right?
If you say, hey, I don't want to go through
all those like five steps in tutorial,
I want to start with step number six
because that is where the real meet happens.
You can do it, right?
You can just jump in the middle.
Okay.
So finally, so how does that all things work?
Well, there are actually a couple of ways it can work.
One is we can have a browser playground
and then a sandbox environment, right?
Which is pretty much docker-based, right?
And that's where we can use browser API,
JavaScript and whatever.
The second approach we can have also is web assembly, right?
So if you can say, hey, you know what?
We want no kind of serocomponent, right?
It runs completely in a browser.
We can do that, but probably in web assembly,
it can be sometimes heavy, right?
Especially saying, well, you know what?
I want to showcase how, you know, like a Postgres
operates when, you know, getting all that Postgres pulled in,
the assembly started, right?
That may not be the best experience, right?
Especially with slower connections.
So that is where docker, right, can be very helpful, right?
So with docker, you can implement whatever you want
and the setup of this service is an open source project, right?
So you can roll your own as well.
There is a variety of existing playgrounds
which are supported at, you know,
core API website, right?
Which can get you started pretty quickly.
Yes, so here are some examples,
and I will of course share, well, slides if you actually slide there.
The online, this is a live tutorial.
You can see there's like a number of projects already started to use that
with, you know, pretty good success.
And you can see with core IP.org showcase that is where all the examples exist, right?
Here are specific projects, right?
There are kind of two sub-repositories.
One is for JavaScript kind of client side,
and other four, the server side, again, it's split
because you may just want to use their client side
if you're using like JavaScript or something
where you don't need a server component.
And yet, if you want to ask some more questions for Anton, right,
or get some feedback, Antonz.org is his website.
So that's all I had, and I would be happy to answer questions
or get out of the way because I think I'm the last thing standing between you and your viewers.
Yeah, we started with docs code, and now we've gone to code docs.
Any questions?
You don't understand, the back-end is also part of this project or not?
Yes, yes, so in this case, code IP, that is your Docker back-end, right?
Code IP JS, that's your, I think, so both of them are open source.
What do you mean?
Oh, you mean in terms of what people run, right, what kind of, so not right now.