keptn Contributing to Keptn, 4 Mar 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Contributing to Keptn Tutorials

Description

This knowledge transfer provides overview of the Keptn Tutorials site internals. We look into the repository structure, Codelabs, and tutorials content organization. Then we discuss how to build the site and run it locally. Last but not least, we discuss how we want to rework Keptn Documentation with Antora.

Tutorials website: https://tutorials.keptn.sh/
Meeting notes: https://docs.google.com/document/d/1M-8d7HnZgswGHrOzal_zl2Jaau1AWN07fyf2PgI2GcI/edit?usp=sharing

Learn more: https://keptn.sh
Contribute: https://keptn.sh/community/contributing/

A

Hello, so today we are doing ad hoc uh knowledge transfer session about captain tutorials and how to develop them. um I will share my screen and show how it works and thanks to everyone for joining so try to do more. Such knowledge transfers going further release my screen, yes,.

B

Are we recording.

A

uh Yes, we are I'm just recording locally, so you probably see the status ah there.

B

A

Is okay yeah, so we will be looking at tutorials. Captain sh, um first of all feel free to interrupt me at any moment. So it's an informal session, it's mostly for coney. I also started a google doc, so if you want to make some notes etc, I'll just make it editable for everyone.

A

So feel free to just put your notes there and then probably mac or somebody take an action item to update the contributing guidelines. Because right now, let's see they're a bit difficult to understand.

A

So what do we see here so here we basically see a set of tutorials available and for each tutorial, if you go, you can see that there are multiple steps you have to pass through and if you completed the steps you basically can complete the tutorial.

A

Also, we have a support for multiple versions. So, for example, if you go to 0.7, you can see that there is a lot more tutorials which have been written at some time, including cargo, cd, aws, gc engine, etc. So they were a lot of tutorials, but for recent questions that are much less and one of the reasons for that is that there are super hard to maintain at the moment due to many reasons and yeah, it's one of the problems we have in the community.

A

Also, if you go to tutorials so when I was working on them in december, I spent some time to stream outline captain and parameters, because, even if they were present, they were not working for users set up some learning paths etc. But generally, these tutorials are still a big problem for us and thanks to everyone, looking into them I'll show how they are organized internally.

A

At the moment, full disclaimer. I would be happy to completely rework the engine. We have a pending task of moving everything to enter, and hence those key doctors so that we could remove duplication, introduce common, macros, etc, etc. Right now, it's not there. So I will show how it's implemented. Now we have a repository captain tutorials.

A

uh These tutorials are basically based on google code lab at least some bits of these tutorials, so google code labs is a project where they have a bunch of tutorials. So you see a familiar interface.

A

It's open source project, uh the problem with that that we actually have a copy of that. So we are not really using the recent version uh older one, um and there is no real support for us to even update the version, because it's just a part of the same repository. So it's basically a hard fork for us and just uh unwrapping the things would be a change. This is why you can see various finds like field bezel here so because google uses bezel to build everything.

A

I have no idea where it even works for the website, so I'm going to show how it works actually for us right now. So what we have, uh I think it actually works, but yeah it's a separate story. uh So what you have now you can see that there is contributing candy with me in the uh here.

A

These files again are mostly copied from polyps and you can easily see if you go to raw tutorial because yeah there is some entry level for captain, but basically the most of tutorials recommended out codelabs.

A

Still there they just commented, and there is uh there are some other things, but basically this very very basic introduction guide. uh Also we have contributing md on the top level and contributing md is a copy of codelabs. It hasn't been updated. It has zero relevance to this tutorial at the moment.

C

A

uh Yeah yeah. This is why I didn't want you to explore it on your own, because it's a bit uh complicated. uh So what we have else here we have site so site is basically content that actually gets published.

A

um You can see that now there is go file et cetera and they get some hint how to actually get it running. So this with me is what you need to follow. If you want to get it running, so npm install would set up the environment for you well, mostly because, due to reasons unknown, for example, it doesn't install gulp, so you will have to install it manually, but basically to do the development you have to follow this guide, so tutorials site, uh good labs um and yeah. This is something you can follow.

A

um Also, I believe there was another contributing uh md somewhere, but okay, let's stop on that. uh So the trick point. uh Apart about that in principle, you can develop on both linux and windows, but it's not how it's going to work in this particular case because, as I said, we use markdown.

A

So our tutorials look like that. um So you can see a bunch of stuff and yeah. You can already see what one of the problems is notification, so, for example, captain dyna trace. It doesn't exist for previous version for a thirteenth version, but for example, if you open uh parameters it exists and you can see how many versions and basically all of them, are copy and paste.

A

So you, if you open photons, you can actually see a bunch of content, including images, etc. Images are not copy and paste. The images are stored in a separate location, um but- and you can also see some macros, so basically, cod labs uh tries to work around some limitations of markdown by uh adding some additional functionality on the top of it. So basically it's pattern matching uh and also all these snippets so way. Snippets selected.

A

uh There is a snippets directory and you can see that snippets also duplicate.

A

So for every version you have to copy paste all the snippets, so javane did it seven days ago for version 13, and you can see that there is a bunch of content there so including some files like feedback md, which obviously have no reasoning to be snippets. It's just a matter of the current site architecture to get it working pretty much uh what else we have in this needs. I also have some files like setup, quality, etc.

A

It's also in snippets because it's referenced a few times from the tutorial, so they decided to actually extract it again. It's if you had to ask the doctor if you had under a macros, it could have been done with native tools quite but this is how it's implemented now and yeah. It's quite a challenge to go through that.

A

So these are snippets and yeah. There is a bunch of them. So basically there is no particular structure, so everything you want to duplicate goes here. uh At the same time, there is no macros, for example, for versions etc. So when you copy the things you actually have to copy all the stuff- and sometimes you have to ensure that the links are correct.

A

uh For example, here you can see.

B

The link is going to 11 by the way.

A

B

Oh, there was one that's going to 13.: okay, yeah.

A

B

I found are going to version 11.

A

uh Well, so it depends because you have to manually update the things so obviously sometimes it gets mixed missed it just becomes a mess, so this part would have been actually moved to templates legitimately, because this, what are templates for you could have a macros here that updates version etc. This is what I wanted to do, but more look at the site. I just want to run it with fire and the new one from scratch.

A

um Well, it was really good for the initial time when we needed to bootstrap the project, but now it definitely hits a lot of scalability concerns.

A

Okay, so what else important about the tutorials you can see that we are using cloud is basically a part of uh codelab which basically does bits of the build and here's one of the limitations coming that. Well, basically, you need to use one of the platforms supported by card and even if you have windows here, it's not actually going to work right now, because right now, in order to build all this happiness, uh all these macros et cetera. You need description, and this script supports only linux and macos.

A

So if you run on windows well, you can uh update the script. If you want or you can use bsl tool, I chose the water option for that.

A

So basically, you can also see that there are some interesting things like putting uh google analytics right here in the script, etc. I'm not sure from where it comes. You can take blame but yeah. I guess jurgen did it at some point so yeah the structure for this thing is, but actually so, if you really want to get it running, it's not enough to just run a gulp file like we recommended here, because golf file won't serve you tutorials. You firstly need to run builder to generate the final tutorials.

A

I will show you how it looks like in the code uh in a second, um so I'm using psl.

A

If you see my screen, I guess I should make it bigger.

B

I right squinting too.

B

Oh, that's: nice. Okay,.

A

So yeah how it looks like um yeah, so basically we have this side. You can see that there is a bunch of additional change uh files uh here, all over again.

C

B

You can give it give me sp, pwd, sorry, pwd, can you give us a pwd? Oh captain tutorial site is that where we are yeah.

A

So tutorial site um yeah, and here we have tutorials. So first of all, we go tutorials and yeah. Here's all this happiness, uh yeah so mike, if you use uh so you use the avi right. Yes, you have a problem yeah for this particular episode.

C

A

You have a builder message, so this will define the same file. I've shown, let me check what is in our history.

A

So 25th, so it's something fresh, okay, so, first of all, you need to run this builder.

A

I believe it's bash.

A

Okay and yeah, you can see that already you have some interesting uh events happening on my clean build because, for example, uh stupid is missing. I have no idea why, let's see.

D

The number is wrong, so basically somebody did snippets with 0 10 and then they continued with 11 and 12.. I had the same issue yesterday: okay, so.

A

Basically, it means that the repository is already bogus, so we can uh fix it while we okay, so okay.

A

So yeah it's not going to be an easy thing right now, but okay I'll just hack around and then I will submit the proper fix. I guess it's not going to help because.

A

So we reference basically both files. This.

A

Okay, then, I will definitely fix it later, uh but you know so in theory, you run this builder and then it prepares all the content, but it actually can serve um yeah so and to serve it. We actually use gold so for gulp we have by the way it doesn't fully clean up when you run rebuild, which is also a problem, because you, if something is wrong, you have a kind of messed up tutorial.

A

um Okay, um so for real me yeah, you basically see all the commands there. So we after you build the tutorials. You first need npm install, so you can get all these tools um and you also need belt. So in galpa there are two ways. Actually, so you can use a gulp serve.

A

I don't think you would need a beast and you can see that you can do some filters, etc. Also viral commands, which basically allow for live editing. So it's also somewhere here.

A

Some commands are just useful, useless, like publish et cetera, none of it's really configured for local environment. It's configured for c and.

A

Just the uh running.

A

Not here so it's powershell, sorry.

A

So I launch gulp serve it's actually quite quick, and now we have on localhost.

A

And here our development is our development version of these tutorials. Okay,.

B

Logos 8000.

A

Yep now it's a default. You can configure that. So basically you get a discussion.

A

You can browse all the changes etc. Again now I have no idea what's happening, for example, version 12., I guess well, we can see feedback so something gets generated, but again, I'm not sure how it works with this. If it's, what is broken? What's not currently, my repository should be a complete mess and actually, if you run the script without minus e, I guess it actually gets generated.

A

I'm not sure we can try.

A

Price, meaning it's following url: what.

A

That's also interesting.

A

Sonic no such fellow director, but you can see that he doesn't actually even break if you run in such mode, and here I guess something is uh hardcoded.

A

So marquee mark is basically this uh templating engine, but why the heck they need to authorize to google drive, I don't know, and they have strong suspicion that it's uh jurgen's google drive so jorge used to work for dana trace. Then he left. So am I better that, after his account got deleted, this thing doesn't work I yeah. So again I have no idea what exactly that I will take a look.

A

Welcome again, it was really nice implementation for the time being, but right now we definitely keep all the technical depth there.

A

So for live development. If you use linux or macos, you are perfectly fine. You can just develop locally. You can browse the things for windows. It's a bit more complicated because for windows you either need to mount a directory and one of the things there that by default, if you use vsl2, so you can just go to linux, ubuntu.

A

And yeah here, basically, you have captain tutorials. So this is my running repository, so in theory I could just edit this path, but the problem that it uses unc by default. So by default, some tools, like visual studio code, won't work with this directory.

A

So you would need to actually configure a mapping and volume so that mount, I don't yeah, it's smart context on windows, so you would need to map this repository if you want uh to edit visual studio code, otherwise it won't work. We can do mapping now if you want- or we can just try to do the bypass. I think it's better touching up this directory, because otherwise they will be hitting this crop every time.

B

A

I I can actually figure it out lately because I haven't. I don't remember how to map it on videos. Well, I guess just map command would work. I haven't done it for quite a while.

A

Okay, I'll take it offline, but yeah generally my recommendation. If you want to do development, I will just connect to my repository.

A

So this is basically the same repository, but it's local, so I usually do development just in visual studio code because it provides a decent level of markdown, browsing, previews, etc. Obviously, none of that really works with tutorials with cloud with all this templating, so you don't get support for that at all.

A

You would need to rebuild this build aside sh every time and it's also broken by now. uh So I guess we will need to do a lot of hot fixes to just get the contributing flow running right now.

A

Basically, this what we have so for editing, I think that any browser would work.

A

Okay, any questions comments, there's so much.

B

um Can you go back to any the the main like where you go into the uh prometheus, the full tour or whatever? Okay there's another weird thing there that I mean just from a usability thing: the display of it, the the rendered okay.

A

um Yeah, actually, okay, I'm opening this.

A

A

Basically, the layout, you can see that some bits are already tricky and not really synthesis syntactically right. So, for example, even here you can see that renderer breaks, because that is how markdown works again. It totally depends on your engine, but syntax wise. It's not correct, um and here, if you go, you can see all this needed.

A

It's just a double opening bracket and that's it right.

B

um Go on, I want there's a specific thing here happening in this tutorial. That's also bizarre just construct, but it's in go to like the next section or something I think it's not in the welcome section, but in most the others it's there yeah.

A

You can see that actually all these session sections are in snippets so because yeah we have multiple uh tutorials and yeah. All of them are kind of copy pasted, so we have to go to snippets. Then it's 13 and, for example, here's our installation guide, which is the most of the tutorial.

A

Here, for example, here we take istio yeah, so you can see that it's install istio and then it's a second layer of indent. So what happens with codelab when it is editing et cetera? It actually creates additional steps. So, on tutorials.

A

So this how it looks like so install istio step number number three, but it gets. Does it automatically from a single markdown file right.

B

Okay, I want to see most of these files have a link, that's going into another document, and it's very bizarre.

A

Yeah also, you can see that there is some timing calculation, so this time and consolidation is again some magic applied by codelabs.

A

uh So here you have duration, 10 minutes and the code labs parses it and automatically tracks it. Obviously, whether it's 10 minutes or not, it's a separate story, but yeah this. What you have uh pretty much the same for other entries, uh so all of that uh modulus legit markdown files, uh some template didn't but generally it's part now.

A

One thing that's worth mentioning: I already opened it so there is, there are additional files like.

A

For example, full tour prometheus 11. Actually it's a good question: why we don't have 12 and 13.

A

Maybe I'm just using code version, so actually, if you open 13 right, we didn't have. uh We have full run parameters for 13.. It's actually quite interesting, because we have uh no blob file for that. Okay, we will figure out it later, uh but you can see that there are also some codelab files. So it's basically additional metadata.

A

uh It shows how to actually pass through the things, and it defines an entry point for that. So you can see url, you can see feedback, metadata, etc and also tags. So tags are what used. So you can see advanced and advanced, gets mapped to this level advanced again. It's a kind of hardcoded logic that allows to capture way is what they're pretty much the same so for log etc.

A

All of the goes from this file and it's how it gets contract constructed also another part which you can see that there are some club tutorials right inside, but for now there is another file here on the top level see here below over that.

A

I haven't worked with this repository for quite a lot a while, but there is another configuration file on the top level.

A

Just second I'll just open one of my patches so that I remember where I actually put the things, because maybe the repository changed.

A

A

I disable disable the captain live demo. So basically it's my pull request that stopped working at some point. Actually this also, I wanted look into so you can see that the results aside are previews.

A

So, in addition to all this metadata, there is also a- and it basically different defines all the views for tutorials. So this is, for example, the default one. So basically, this is the page we open uh when we load it.

A

So this one here you can see that there are also some files. For example, there is new json which basically provides some link options, etc. So, for example, here you can see that there are some tutorials pinned.

A

uh You can see that these things don't make much sense these days, so they update updated. We also open 11th by default. So when you open the default page right now, 11. So when I was updating this site, but then it was johannes and giovanni doing that and looks like they forgot to modify so here by default, we go to tutorials for elevens, not for 13, and this one of the problems. I'd say we also need to fix.

D

I think there's also a problem with if you go back to the tutorial site um to the webpage, if you click on captain version 6 or something and then from take the prometheus tutorial to the left, left left first, one: oh yeah, okay,.

A

D

Okay, because I saw some problem yesterday there that some of the versions were not, I think some of them were removed, so six, seven and eight or something like that.

A

Well, uh yeah, it's probably some of the versions were removed, uh but here one of the problems is that it has no russian tech at all, because basically it was the first version of captain when uh all this engine was introduced and basically when they needed a new version. Instead of redesigning this site, it was basically extensive, so just copy whatever files, and it has been extensive ever since so every month there is a bunch of copy based across all these repositories and basically one could get completely lost.

B

C

B

We still have pages on the web for tutorials for versions that we've removed from the documentation. Why aren't we removing.

A

When you clean the top, huh because nobody cleans it up, okay,.

C

A

Yeah also tutorials uh works in funny ways, so sometimes I mean cod labs, so I'm pretty sure that these versions were hidden before, but now they appear. For example, uh in my case I tried to hide.

A

Explore captain without installation- and it was hidden for some time, but now it appears here so basically, this patch, which I was showing to you.

A

Closed it, but the patch which removed this tutorial after you disabled to the public demo, it stopped working again with this amount of different bugs and the build script without checking. I have no idea what exactly breaks, uh but by now I assume that our engine is half broken, still displays the things but yeah, that's it.

A

um So what is important about these views that yeah? You can see that there are some such visualizations and, for example, view so it's also view for version 13.. So this is a version's vector. uh Basically, this version inspector you have is just this feature of use from codelab, and here when you take, for example, the version captain.13.

A

It opens you this view and this view you can see that it matches basically things by uh tag, so it displays all codelab entries which have this tag. It also excludes some items because otherwise it just pushes everything back on the page as well, because this is the default behavior of good luck, anything that will copy all the images.

A

A separate story um and yeah one thing or with all these filters that some something definitely stopped working. I didn't know what, but all the things will be fetched just uh by a label and in tutorials in principle you should be able to just disable them. So let me open tutorials again.

A

Starting to get lost, yeah tutorials, so in tutorials, for example, get this live demo.

A

Just yeah a couple captain public demo, so this is basically metadata for what I wanted to remove, and here you can see that there is no longer time for that, so it shouldn't have been even fetched, but it was- and maybe it's just because we do not clean up the workspace correctly but yeah. I don't know it's a public json. So here we have the charts, but here I believe it was explicitly disabled, maybe not get status published, so maybe something changed uh but yeah overall. This is how it should work.

A

So you touch this metadata and hide tutorial through that you can put additional labels so that it gets fetched uh correctly. um I also try to use this labels to implement learning paths. For example, if you click quick start, you get level introduction same for football, etc. So all of that actually gets through category and sometimes level matching.

A

So he that's how it works.

A

So categories are basically here, so we also have parameters etc and again all of it is version dependent.

A

Things are complicated, have broken, but still we need some commenting.

A

B

I mean what are we supposed to so it's broken. Can't author nvi, you said.

A

Well, you can order nvi, but it will be definitely a challenge because all these repositories, with a lot of copy paste, with difficult navigation through these files, so my strong suggestion would be to consider using something like visual studio, etc, because it really helps with navigation and reviews.

A

I also use veeam for big patches.

A

If you want to do some development without previews and other things, I think it will be super complicated for this request today.

B

Okay, I mean I'm looking at this stuff. The con, my view is, the content of these tutorials is appalling. The structure is appalling.

B

The writing is pretty bad. I mean how much time do we spend bandaging this versus just start over.

A

It's actually a good question, because uh uh if we would just build something quickly with entera, maybe it's something we should consider but yeah the problem that uh migration from markdown uh to ask talk in this case won't be trivial because all of all these macros etc.

A

So you cannot easily automate that otherwise, what I would have done, I would have just used one dock as converter and basically a few github actions and you would have got everything running, but right now it doesn't seem to be possible for this particular repository. So yeah. You need to create a hard fork of everything, um but in this case it's also a question whether it's just tutorials or the entire documentation side and whether it's a project of a size.

A

You can uh work on that right now. So this is why mac? I just wanted you to study these tools first, but everything before importing from this story, because it's going to be a picture.

B

Yeah um another question: do we I mean, is there do we want, apart from the what the tools currently are? Why do we want tutorials in a repo separate from the rest of the documentation? I.

D

B

A

Well, technically, how I would see that, for example, we have.

A

So, for example, for parameters, so primitives mostly describes uh parameters, integration service and for them I would like to see these tutorials actually being integrated to captain country, and here we have primitive service maintained by christian and the team.

A

So my vision would be that all the communication for parameter service, whether it's tutorial, whether there are docks, pages etc going inside this repository, so that uh whomever does patches etc as a part of their pull request. They update the documentation as well. So this is what we call documentation is called for: real, not keeping docs in down.

D

Yeah, that's a very good idea, because also the ownership might change a little bit. This is what we have with the same problem with the dyna trace service in captain country and we're referencing lots of stuff, and if, if we have lots of snippets in every place, then we basically end up changing something that somebody else needs, probably in a different way and also the captain examples come into play then as well right.

C

A

uh So yeah, this is basically uh how I would like to see and if you want to take a bite, for example, just putting um some tutorials in the repository and see how we could build it with entera. I actually wanted to do that. So if I ever get a few days of non-interrupted time, this is actually the first thing I would like to do just rebuild this engine and see how it works uh well and do not hope today to do that. So I'm not sure whether you saw it york.

A

We actually created the google summer of code project id for that, so we added a project id a new documentation site engine which is basically well basically describing all this runs in text more or less and yeah. So as a part of that, you would actually want to rework that so, if you're potentially interested to be a kind of stakeholder or a mentor for this project,.

A

But basically, I'm not sure, what's the timing, whether we would get accepted to gsoc whether we have a student working on that, but regardless I just want to have to make it happening at some point.

B

Yeah right because yeah, because one thing that concerning right now, it's dinotrace and prometheus, but someday there's gonna be a lot more of these right. Well, the problem.

A

That there was a lot more, but it wasn't sustainable, because if you go to version 0.7 here you get argo cd, which is essential, which we promote uh not no tutorial for the recent version, even though even a captain team uses rxcd in some cases, hd devops imports.

A

Custom notification service- I think it's obsolete, because now we have a web hook, service, etc, but okay, also installation guidelines which are again quite important. So if someone asks how to install captain on gt, then this is where you would like to point. But again this is dated it's no longer relevant because we mostly moved to hand, charts, etc and then mini cube again important for those who run on the macos want to evaluate it.

A

Openshift again important, then, and we want to have more tutorials for tools for integrations, but with the current engine is just not sustainable. I mean we still have an open question who maintains dana trees tutorials I mean on a regular basis and use all the current structures just impossible to actually get it maintained. So it's a huge endeavor.

B

Because? Okay, because what it's like just saying like for all you're talking about putting all the prometheus stuff into the prometheus repo right and.

C

B

The docs repo is the stuff, that's sort of neutral that it doesn't matter.

C

A

B

A

This is correct, uh although even with that uh there are a few uh optional obstacles, because uh we also have this compatibility matrix and it means that, uh for example, remedial service and hence the tutorial would be compatible only this particular version of capital, and it means that you actually getting the troubles with configuration matrix again. I don't think it's a really big problem, because I would rather prefer to have just tutorial for the recent personal primitive service and for the recent version of captain and that's it.

A

I don't have feel strongly about these versions. I.

D

A

Whatever, but at least for the recent version, I would like to see it as a kind of running document in the master branch and for the rest, we can use version tags when it's really reasonable to have a confession of the tutorial. Maybe a branch.

B

I mean I'd like to go back just looking at it. It seems to me that we've got way too many tutorials that are covering the same material yep, and then we've got all these things about how you do this and then we've still got installation stuff stuck into the what's called reference pages for like sli and slo, and I mean it's: it's.

D

All installation.

B

And we're that's where we're devoting all our time and what I have not completely. You know this is my I think, fourth or fifth week, so I'm still learning on this stuff, um but.

B

We're not we're all I'd like to do a mapping of what we need a tutorial for what the tasks are and which of those tasks are generic for everybody and which ones are specific to you're. Trying to your prometheus or dino taste is that nuts is that a nutsy place to start.

A

A

Yes, sorry, I just wanted.

A

A

Issues in this repository.

A

Sorry for the determine.

B

A

Try to create these things right away,.

A

Okay, so you were basically talking about the specification part right.

A

I personally think that we should.

A

Remove the most of version, specific content from here I mean any of these things again should go to uh repositories so, for example, installation etc. So this just goes straight away to premiere service right.

A

Pretty much the same for dyna trace all of the things again go to data trace service, which is basically on the same level here then, what else do we have on this side?.

A

Yeah then we have all this content web look, integration, etc. All of that is important, but I don't think that it has to be written as a part of a particular fashion for the most cases.

A

Yes, so some content, like gpr et cetera well, we can aggregate that, uh but my vision for that would be that, once a new release is done, we just uh freeze the recommendation for the previous version. Take it from whatever branch or tag basically do not touch it unless it's really needed. So we should stop doing this much massive patches by developers who have to update multiple uh versions uh so that they don't get lost.

B

Okay you're now I'm just you're sort of losing I'm not sure what I'm I'm losing. You.

A

Yes, uh so, for example, yeah, I'm just looking so here, we have, for example, patches that update multiple versions, how it looks like it's like that, so you have to duplicate all the content for 12's, then update 13 with the same content and obviously something will get good.

A

So it complicates reviews, because you need to update multiple places and basically makes no much sense to update the older version in the most of the cases, because we recommend using the latest version um the well basically this one months for this cycle. I think it's okay for the captain and the current stage you might introduce, let's say one year cs or whatever later, but maintaining these tutorials.

A

I think that okay, we release them, we pin them, and then we update everything from the new version.

B

Okay, yeah um we're jumping around so yeah.

A

ah Yeah, I think we go beyond tutorials, but I guess we're on the same page. We need to do something about that, and also there is this page. I have no idea from so it basically points to all these filters, etc, but it works only as long as you have a default version. I pinned to developments.

A

If you switch to 13s, then basically, things get quite difficult for you, because many filters will just provide empty entry.

A

The entry okay, you can see that this behavior just resets your filters.

A

Okay, so any questions.

B

Oh, I I mean I'm just I have. I have no idea what to do next here.

A

Yeah, so my suggestion would be to just uh take newcomer friendly tickets, we discussed so the main point is just to ensure that tooling works for these things, uh but yeah. I wouldn't expect you to spend too much time on.

B

Okay, I mean there's, I you know I. I was thinking that, as I was reading through this stuff, I could fix. There's all sorts of places where, like set up, one word is used as a verb, and you know little things like that that I could just do that as I go, but.

C

B

Studio and figure out how to use that and.

A

Yeah, so for me, my recommendation would be to just understand how it works using the goal of reworking that, because tutorials as they exist now they are just well. Basically, we can try to watch them, invest much of effort uh to keep them running, but I don't think it's the right thing to spend time on yeah.

B

I mean, like we had a bunch of engineers who, instead of doing good uh documentation, set just did all these tutorials I mean most of these are not. I don't see the point of most of these tutorials. You know when you look at them. It's like what is the goal here.

A

Well, uh they're reasonable the program that was too many installation steps and uh not clear what would be the goal well. Actually, there are quite good introductory things uh for some cases. uh I think what we would achieve, etc, uh but actually yeah so.

B

I wouldn't put that in a tutorial. I would put that in the intro to the product and like the getting, I guess whether you write the tutorial, you know for the tutorial. The tutorial is going to be basically a cookbook sort of thing. Do this and look at this happen? Do this and look at this? It's not look at the architecture. These are all the pieces that go together.

B

um We're only going to mention it. You know it's like that's that should be in regular guide material.

A

Well, uh basically, yes, I don't see much difference between guides and tutorials to be honest. uh Well maybe for technical writers uh there is no difference, but uh yes,.

B

There's the massive difference yeah it's I mean it's a whole different. You know it's a whole different style and you know and purpose uh yeah.

B

These tutorials are full of information that, if I'm using the system, I want to go back and reference a tutorial is something I go through once maybe twice to get started and get the big picture and then and the guide material I mean we there's a limited amount of guide material that people should be looking at. Very often, we need really good reference material and instead of a reference, material is written like tutorials and doesn't have. I don't know somewhere in there, there's those blogs back.

B

You know, I finally saw you know a thing for shipyard, but you know what I'm saying is uh yeah so, and I mean I don't know, then how we you know. Obviously we can't fix everything at once. So how do we go at it? But so, okay, because I was thinking you wanted to really try to get these tutorials straightened up. You just want me to cruise through and get a view of what a mess they are right.

A

Yep uh so yeah, there are two ways: firstly yeah. Let's say you get something like one week of smallest, uninterrupted time. We just work together and get the under engine running, or maybe we do it as a part of gsoc, but so my concern about having this project in jsoc that, if it's done by the end of summer, so it's still multiple months until we actually have it running.

A

So I would consider that if we really seek help for this project, maybe we should go through lfx manage.

B

Yeah all I know I mean I'm not a tools person, but I also know at cloud b's the just before we merged training in docs. um We brought in this guy named jeremy, who was, as my grandfather said, I'd like to buy him for what I think he's worth and sell him for what he thinks he's worth.

B

He knew it all they are there. You know there was nothing. He did not know more about than anybody else in the world and the antora that he was setting up was an absolute disaster and then we got merged, and that was something that tammy and ben actually knew what they were doing and we just converted over and used their stuff. So that's the one thing that concerns me about doing this with gsoc is: do we get somebody who knows what they're doing enough to set it up right or do we end up with a.

A

Well, yeah I actually reached out japan asked for some expertise. Maybe they'll cut cut this part from the recording but see I didn't see anything secret. um So, okay, if we could get some advice on how how cloud is on terra, maybe if they would be willing to open source the engine.

B

Probably tammy tammy is of the. um Why would I do anything for open source.

C

B

And she's not going to help me so.

A

So, let's see anyway,.

B

A

Don't know what sort of.

B

Yeah, it's like it's just.

B

I mean there as a there I mean there's another there's a stop gap, thing of which is to figure out which of these tutorials are somewhat good or which have information that should be elsewhere and and define what tutorials we need and try to just write those and do them in as a section in the main docs that are there now and then convert everything to antora at once.

A

Yeah so a lot of work, but I think that it would be great if you could pass through that.

B

Yeah, well, let me go through and do now, because I would you know I was thinking I'm supposed to read this quickly and then I was supposed to update these to work with mac, which is I'm still fighting the mac too. So well,.

A

It should work with mark, I haven't uh tried, uh but.

C

A

So I'll probably see what's broken in the build engine because it yeah it looks like some hardcoded dependencies on your guns, google, drive, etc. Actually, this is something I didn't receive by today's meeting, so I have.

B

No idea we're gonna get deeper and deeper here.

A

Yeah, so I have no idea what it actually gets displayed, uh but let me know if I forget: the tutorial still works.

B

Okay off the top of our heads now, what I do see is we need a good tutorial that quickly gets me a non-production environment, something I can install on my laptop using k3d and I get kept in and I have something else. I.

A

Strongly suggest, looking at the tutorial created by uh adam.

B

uh Right, no, I'm just let's not fill it in I'm just saying what do we? Let's say we have nothing. We have something, but let's say we have nothing. What tutorials do we need.

C

Yeah, that's the one that we need is to get.

B

Captain installed on k3d.

A

B

A

Or on docker, but the thing that get running pretty quickly so currently: oh, how envisioned it would be a learning path of three items again, some something good go broken here, because there were four two dollars.

A

So basically the idea was for learning past that you start from quick start or maybe watching it live. So it's currently disabled on this page. Then you go through full tour and then you explore some particular use cases like quality, keys, etc for separate tutorials regarding the installation. So quick start is what we actually need.

A

In any case, the current quick start is uh okay, it's focusing basically on installing captain a few other items. So you see that steps are really small because it actually points here. The captain's website. Right again, it's something called uh I just had to pick patch but yeah. This is basically what I rewritten in december and it used to work.

A

C

A

Etc, but still it's quite heavy, so this is minimum requirement and even on this minimum requirement it doesn't work. So what um andre? Sorry? uh What adam created he created.

C

A

That is based uh basically on a kubernetes under kind instead of kit 3d, it's a much more lightweight. Well, it's still quite heavy, but it gets you quickly to a hello world running.

B

A

My recommendation would be to actually consider so. Well sorry, it's not that one. It's also a good one, but not the one. I wanted to show.

A

A

And remember one college actually points to this one, so I will double check um but yeah anyway.

A

There is another one which is hello world, so this one basically shows how to uh set up captain uh in kind uh out of the box, and there is another new tutorial which shows just captain this kind.

A

I need to find it, but it's also quite useful.

A

So I'll definitely find it.

B

And now the part one of christian's video that he did a couple of weeks ago. The second part is setting israeli development environment, but I think the first part is just getting your captain part up. Yeah.

A

Let's focus on the user story because developer environment is for contributing, it's also important, but it's a separate flow.

B

I that's what I'm saying part two of his videos is developer. I think part one which says it's, but I think it is. I don't think it's wrong for the user environment. It just gets kept enough, but it's a video.

D

B

D

B

Why? Because he split it, he deliberately split it into two videos, and I think that may be the case.

A

So yeah for the tutorials uh sorry I had to go into my inbox to find it quickly.

A

So yeah there is a repository called uh the kind captain. So again it's a separate repository and it basically bootstraps captain in docker right away so and just showed the guidance.

B

So is there, can we just start using this right away.

A

So I'm just going to show it to you: let's see what I so, it will need to pull the image.

A

Also interesting, maybe there is a bug in this tutorial or I don't present the deploy to the docker image.

A

So what I'm going to do.

A

I will just take latest.

A

Maybe it's something related to permissions, etc. I will report it to adam.

A

Looks like this repository doesn't exist at all anymore, but yeah once it's getting just creates a captain hello world in kind, and you need just.

A

Just need to have a machine with docker, so the rest will be automatically.

B

So, and this this is something it's a docker container that gives you kept in that small enough that you, a reasonable person, could put it on their laptop yeah.

A

Exactly so, I'm just looking into the repository and I see that adam didn't deploy 00.5, so I believe it's just his local machine right now, okay, but but I know now that I can use the resident.4 and maybe it will start.

B

Doing something.

A

Oh, it's still pulling the image. I will just show how it looks like from user's perspective, so you can see that it does captain installation, etc.

A

So you can see that it takes a captain, it uses, k3d, etc, and so that it will use kind.

A

This time already exist, I'm not sure whether it will continue after that.

B

uh You already have a cluster with that name.

A

Yeah, so it's also something I will probably need to report to this repository, but I think that in principle it would be a really good uh to start demo if you could get it working properly.

A

uh I will suggest that we actually move it to sandbox.

A

If I don't agree, but okay, it's one of the ways to actually bootstrap things easier.

A

Somebody wasn't making notes as usual,.

B

A

Well then, it will be your homework.

B

I I could, I the you, did the one screen, but I was looking at minuscule type flying by really fast and listening to you trying.

C

B

A

So I'm just paying agenda.

A

So let's go back to okay, so do we.

B

Want to put on that list the strong possibility that we should just abandon the um the tutorials repo and whatever we're doing.

A

B

There's all that jurgen stuff and.

A

Documentation school.

B

What is the source for? What adam did is what adam did in markdown.

A

What uh this one.

B

The tutorial we were just looking at yeah.

A

uh He's just very keen in the representative, it was basically.

B

Oh, this is the readmemd for the repository.

B

Okay, no comment about that, but so, but.

C

A

Think md well for a simple demo: it's perfectly fine, so you have a simple description. You have all the content, it's self-contained, so I don't have any issues with it and basically this is the trigger he uses. So basically sending this cloud event will trigger the execution.

A

Okay and this demo also broke, so I have a really bad lucky but yeah what so, after all the things happening so.

A

Also, coconut stuff, like this.

A

So definitely this tutorial will also need some uh polishing. If you want to do that.

D

B

You know why adam wrote this I mean: did he have a specific purpose for writing this.

A

Well, firstly, uh showing everything from kind, because again our tutorials are super heavy. It requires users to set up kubernetes. I mean it's always a challenge, so he took kind because this kind you can actually use native docker image, can't find.

A

After I disabled it, it will show so that you need to disable it right.

A

So I will probably play around with this tutorial after the meeting, because I actually want uh to get it running again uh but yeah. I think it's a good bet to actually have a lightweight starter, and now it's just requests cleaning up everything manually, because this tab script isn't full tolerant. So when something fails in the middle, we are basically screwed.

B

All right yeah, it would be not if, if we could have that docker thing and then and then in the other places like, I think, like the sol and sli what are called reference pages, they begin with telling you how to get kept and up and running on k3d years I mean it's: there's installation instructions everywhere and.

A

So my suggestion is that we used to just study this engine a bit prepare your development environment. But I think that our plan is to move out of this as soon as possible and if it helps, I would be happy to just prioritize it and to get it done.

B

Except you're already, without doing that, your words remember if we burn you out again, I'm gonna have people from two different companies after me with pitchforks, and god knows what else.

A

B

You out again and after what you went through last year, I've got to think you're, fragile.

A

Well, I'm still going through it.

B

And you're still going through it yeah. So so, let's be realistic about what you can do here.

A

I understand uh and yeah thanks for your concern. I actually agree with you, but.

B

I know this, but I mean the thing is: is with you also what you thrive on is doing stuff like this, so but so, let's we'll just be careful, I'm not saying don't do it, but um okay, so, okay, so I'm doing analysis only for now and I'm not even worrying about trying to fix this. I'm just scoping out what.

A

Yes, scoping may be just writing some really simple contributing guide when pointing to this recording and some basic steps. So definitely no need to write something extensive.

B

Right well, like you said what I did um well what I started with the contributing I just going through and reading everything and noting. What's where and making comments, and I did something like that. With the reference um pages and stuff I haven't yeah, I haven't gone through everything, but I'll go through because, as I say, some of these tutorials have some really good information that I don't think belongs in a tutorial, but it belongs someplace else where people can find it so yep.

A

um But yeah right now, I just uh I think it's a wasted effort uh to rebuild the documentation account, I think so. Why would just uh create spin-off for dogs? Captain io based on cuba, uh sorry based on entera and then actually think what do we do with the rest of the content, the remaining huge, but maybe moving over the things.

B

Right, actually, you know, I I don't know for antora. I think where you get into it's more the implementation.

B

When you start having a lot of text that you reuse and stuff, I'm not sure how big a job it would be, but I can convert mark down to antora or too and to ascii doctor pretty easily yeah yeah. It's pretty.

A

Easy by default.

B

And what I'm thinking is, I think, a fairly simple antora implementation would, let us do asciidoc versions of the markdown files that we've got now pretty easily. Then we it gets fussier as we start having. You know all the different stuff that we pull in, but but maybe but maybe that's. The thing is that we do a quickie just to get everything into ascii doc under antora and then.

A

Actually, what we could try, we could try ascii dock. We could uh start just a new repository dogs, kaplan captaindocs.github.com.

A

So I could create a simple github action that just uh shows the thing, so it would be kind of our sandbox to play around. For example, we could offer adam to be a kind of pilot project to be moved to the new tutorial to the new uh recommendation.

B

Right and actually because right now, the tutorials are in their own repo. So if we set up a new repo which is actually beginning of our antora set.

A

Yeah, I think uh we set up a new repo for documentation, deliberately this plan to not put too much content there.

A

Basically, using contour is the build engine things from elsewhere, through references and just putting these references in place.

B

C

You're, finding.

B

All the stuff- that's in jurgen's, private, repos, etc, and I wouldn't have to learn this trust me. I can do a lot of conversion to ask a doctor for what it's going to take me to learn to use visual studio.

A

Well, uh the problem is not this conversion. The problem is putting documentation in the right place right also, we will have a question about readme files, because uh readme files for services also hosted on artifact hub, so you can just switch towards keyboard if it's not supported in our default hub.

A

Well, artifact hub script is also kind of yeah. Well, it's not dark magic, it's quite straightforward, but I would rather be careful and maybe start from uh supporting markdown in the enter engine so that we can gradually move over the things.

B

That's right, antoine will build markdown. Won't it well.

A

You don't get all the features all.

B

The facilities but yeah.

A

There are tools for that.

B

But what um back to, but I'm I'm sure, some place, we're going to have some place on the web or in the doc set where it says tutorials and then, if we have some of some tutorial information in prometheus and in the dynatrace are those going to get referenced from there.

B

I think for oh yeah.

A

A

So maybe I will spend some time today to create this pc, because now I am excited and maybe it will take 30 minutes to have a pc running.

A

B

That would be fairly exciting as long as you're having fun. All I ask is at the point that you're not having fun and starting to feel stressed, walk away.

A

Well, I wanted to work on that for two months, because every time I look at these tutorials and this documentation, I just want uh to nuke it from the orbit, because you can ever anything, that's not a good joke these days, uh yeah yeah. Otherwise I want to get rid of it.

B

Right, it's like when I look at the other docks I mean yeah and it's like there's so much, there's stuff. You know I can't do internal cross references very well in markdown, and I I can't make inline comments, and you know this sort of stuff, but there is stuff, could incrementally work on but yeah when you looking at these tutorials.

B

It's like this needs to just be started over from scratch and and we need the readme for this new repo needs to specifically define what a tutorial is and when you can write a new tutorial and.

A

B

Fact that an existing tutorial lacks 10 of what you want, you do not write a new tutorial. You fix the existing one um that we've got too much of that going on. So.

B

Excellent okay, so we have a plan only you have to promise me that if you start feeling really stressed you walk away from it. Okay,.

A

uh Yeah I make no commitment, I'm just making notes, I will publish it to dogs and once the poc is ready, maybe we could get other contributors.

B

Yeah um yeah once there's a repo. um Well, I could take some file and put it over there and switch it. Tasky talked or you're saying just build markdown initially right and do ascii doctor conversion. Next, okay! Well, anything you want. If you want, you should not be spending the time converting files from markdown to ascii.

A

Oh well, I will uh probably create an engine that uh converts to them right away because we already have experience with pandora and with creating github actions for jenkins. So this is what I will do here as well. I guess okay.

B

Cool, okay, okay, this was fun, and now I have a better idea of what I'm supposed to be doing. I'm just reading this crap, and it's like what am I supposed to be doing with this so now I know what to do fabulous, um so this is probably it for you I hear is well. They said in vienna. They take friday afternoon off. Is that true in switzerland also.

A

Well, not really, in my case, I won't work too much today, because I have some other things to do yeah.

A

I must make my house this week, but otherwise I will play around for me friday. It's always something like hacking time so.

C

A

Have meetings any meetings left for today, which excites me.

B

And hiking, I think distresses, you right does that help you calm down, yeah.

A

A little bit well, this is definitely something hiking running et cetera sounds like a good thing. What's.

B

Your weather, like you, still have a lot of snow right.

A

Except the mountain, so you can still go 700 meters up from my place and of the remaining initiative city. So there is snow, but on my elevation level now.

B

So will you go up to where the snow is or were you are you starting to see anything like spring or yeah.

A

Well, uh hey it's spring, I can send you photos later yeah. If I want some captain chad but yeah, that's it.

B

Cool we'll go off have a wonderful weekend.

B

And uh we will talk next week or unless you have something I'll be watching slack over the weekend too. Don't worry if you need something before that, so paying me if you need me, thank you so much for all of this.

A

B

Take care have a great weekend.

A

I will get the video published as soon as it renders it's quite a long one. So maybe you won't know.

B

Okay, fabulous bye, bye.