[00:00.000 --> 00:08.020]  We are starting with the first talk in the Sovereign Cloud
[00:08.020 --> 00:10.220]  Dev Room, and it's my great pleasure
[00:10.220 --> 00:14.060]  to open the stage for Max, who's going
[00:14.060 --> 00:17.220]  to elaborate on how he created a documentation framework
[00:17.220 --> 00:19.420]  for the Sovereign Cloud Stack.
[00:19.420 --> 00:20.140]  Enjoy.
[00:20.140 --> 00:21.260]  Have fun.
[00:21.260 --> 00:22.220]  Thank you very much.
[00:22.220 --> 00:22.900]  Hi, everybody.
[00:27.380 --> 00:28.740]  Thank you.
[00:28.740 --> 00:31.340]  How did we create a documentation framework
[00:31.340 --> 00:33.580]  that works across a group of vendors in the Sovereign Cloud
[00:33.580 --> 00:34.500]  Stack community?
[00:34.500 --> 00:35.340]  This I will show you.
[00:35.340 --> 00:37.020]  My name is Max.
[00:37.020 --> 00:40.780]  I'm knowledge management engineer at the Sovereign Cloud
[00:40.780 --> 00:47.100]  Stack, and my background is broadly in web development.
[00:47.100 --> 00:49.420]  The talk, TLDR, what is it?
[00:49.420 --> 00:51.380]  Basically, it's a set of GitHub Action Workflows
[00:51.380 --> 00:55.220]  to copy, mark, down folders and files from many As
[00:55.220 --> 00:57.180]  to one single B. And once that's done,
[00:57.180 --> 00:59.140]  B is being built into a single-page application
[00:59.140 --> 01:02.900]  resulting in the Sovereign Cloud Stack documentation
[01:02.900 --> 01:05.980]  at docs.scs.community.
[01:05.980 --> 01:12.420]  And here, pull out your mobile phones and have a look at it.
[01:12.420 --> 01:14.900]  And I will now elaborate what's behind this.
[01:14.900 --> 01:17.580]  So what is the Sovereign Cloud Stack?
[01:17.580 --> 01:19.260]  The Sovereign Cloud Stack combines the best of cloud
[01:19.260 --> 01:21.420]  computing in one unified standard.
[01:21.420 --> 01:24.060]  And SCS is built back and operated
[01:24.060 --> 01:29.180]  by an active open source committee worldwide.
[01:29.180 --> 01:31.100]  Yeah.
[01:31.100 --> 01:36.380]  This is the SCS stack, and it's made up from many modules.
[01:36.380 --> 01:39.580]  And yeah, it's quite complex.
[01:39.580 --> 01:43.940]  And there is, yeah, of course, documentation,
[01:43.940 --> 01:47.540]  but it's heavily distributed at different places
[01:47.540 --> 01:48.860]  on the internet.
[01:48.860 --> 01:51.780]  And that's quite difficult to keep track on.
[01:51.780 --> 01:52.740]  Where do I have to go?
[01:52.740 --> 01:56.940]  Where I have to be routed as an integrator developer.
[01:56.940 --> 02:00.340]  That's quite a challenge.
[02:00.340 --> 02:03.540]  So as an integrator and operator,
[02:03.540 --> 02:06.220]  you have to manage different documentations
[02:06.220 --> 02:09.060]  in different Git repositories and different docs.
[02:09.060 --> 02:11.460]  And it would be nice to have them within one platform
[02:11.460 --> 02:17.060]  to search and to have guides and tutorials and references.
[02:17.060 --> 02:19.900]  And a great DX or UX.
[02:19.900 --> 02:23.420]  But how could you do this?
[02:23.420 --> 02:25.220]  This was my challenge.
[02:25.220 --> 02:27.660]  And the aim and requirements for the documentation
[02:27.660 --> 02:30.580]  is it has to be like a minimal rule
[02:30.580 --> 02:33.700]  set where the approval is basically a no-brainer.
[02:33.700 --> 02:39.020]  And all doc files will reside in one place.
[02:39.020 --> 02:43.580]  And it must be, and this is probably the biggest challenge,
[02:43.580 --> 02:46.820]  a low entry hurdle for companies with existing repositories.
[02:46.820 --> 02:49.060]  Because no one wants to change the whole documentation
[02:49.060 --> 02:53.620]  if it's being consumed by another stack, basically.
[02:53.620 --> 02:56.260]  So no one has to make any major changes.
[02:56.260 --> 02:58.580]  And then we were thinking about,
[02:58.580 --> 03:01.900]  could it be made up with Git sub-modules?
[03:01.900 --> 03:05.500]  And no, this is too complex to manage.
[03:05.500 --> 03:09.220]  And Git subtree was then, OK, this could be nice.
[03:09.220 --> 03:12.900]  But actually, it's not cool, too.
[03:12.900 --> 03:15.180]  And then other vendors said, no, we
[03:15.180 --> 03:21.180]  don't want to change anything in our existing repositories.
[03:21.180 --> 03:24.780]  So then we had a great community hackathon in Cologne
[03:24.780 --> 03:28.100]  in November 22, hosted by Plus Server,
[03:28.100 --> 03:30.340]  where we have developed an eight-hour straight
[03:30.340 --> 03:34.660]  in a tunnel working prototype with a custom GitHub
[03:34.660 --> 03:38.700]  actions workflow or combination of this.
[03:38.700 --> 03:40.260]  And this is one of the great things
[03:40.260 --> 03:42.140]  with the sovereign cloud stack community
[03:42.140 --> 03:46.340]  that everyone is joining forces to actually elaborate
[03:46.340 --> 03:49.260]  on the common challenges.
[03:49.260 --> 03:51.220]  So yeah, thanks also.
[03:51.220 --> 03:55.580]  Shout out to Ramona and Tim, who worked on this prototype
[03:55.580 --> 04:03.900]  with me on this day from OSISM.
[04:03.900 --> 04:05.220]  Yeah, so how does it work?
[04:05.220 --> 04:08.500]  Basically, it's GitHub actions workflow.
[04:08.500 --> 04:11.620]  It's actually three workflows, as you see here.
[04:11.620 --> 04:18.380]  And the whole concept is it's a Docusaurus React-based static
[04:18.380 --> 04:20.020]  site generator.
[04:20.020 --> 04:21.580]  You may have heard of.
[04:21.580 --> 04:24.900]  It's outsourced by Meta.
[04:24.900 --> 04:29.420]  And the three action workflows are
[04:29.420 --> 04:33.820]  divided in collecting all the different documentation files,
[04:33.820 --> 04:36.220]  then distilling them, that you only
[04:36.220 --> 04:38.660]  have the markdown files from the repository,
[04:38.660 --> 04:42.380]  and then it's being built and deployed.
[04:42.380 --> 04:44.700]  Let's jump into how this works.
[04:44.700 --> 04:49.220]  We defined docs.package.json, where
[04:49.220 --> 04:52.500]  you define which doc files you need,
[04:52.500 --> 04:55.380]  from which organizations repositories.
[04:55.380 --> 04:59.140]  So basically, it's a package manager for docs.
[04:59.140 --> 05:02.340]  So in the first line, you have the repo with the organization.
[05:02.340 --> 05:05.820]  So sovereign cloud stack slash docs is the first one.
[05:05.820 --> 05:08.860]  And then you define the source directory,
[05:08.860 --> 05:12.780]  where the docs files reside in, or the folder.
[05:12.780 --> 05:15.340]  The next line is then you define the target,
[05:15.340 --> 05:17.060]  where should it be placed in the site.
[05:17.060 --> 05:21.940]  Currently, there's a community page and a docs page,
[05:21.940 --> 05:24.220]  docs for technical documentation, the community page
[05:24.220 --> 05:26.860]  for how we organize in the community,
[05:26.860 --> 05:28.420]  and also a contributors guide.
[05:28.420 --> 05:33.780]  And the label is then how it should reside in the navigation.
[05:33.780 --> 05:38.300]  Then the first workflow is reading the JSON,
[05:38.300 --> 05:42.580]  and then defining a matrix strategy within GitHub Actions.
[05:42.580 --> 05:48.060]  So for each element in the docs JSON,
[05:48.060 --> 05:53.060]  a workflow is being run.
[05:53.060 --> 05:55.100]  So this is the whole synchronizing and distilling
[05:55.100 --> 05:55.900]  workflow.
[05:55.900 --> 05:58.420]  We call it distilling, because it's
[05:58.420 --> 06:03.660]  like in a distilling process, refining what has to be done.
[06:03.660 --> 06:06.940]  And all the source code, because most of the time,
[06:06.940 --> 06:08.820]  there's the source code, and then in one doc folder,
[06:08.820 --> 06:12.300]  or docs folder, there is all the documentation
[06:12.300 --> 06:16.900]  which we want, the other source files we don't want.
[06:16.900 --> 06:18.660]  So we're distilling it.
[06:18.660 --> 06:22.060]  So we'll quickly go through the workflow.
[06:22.060 --> 06:28.740]  The first one is checking out the repository
[06:28.740 --> 06:33.860]  with Secrets action token.
[06:33.860 --> 06:37.580]  Then it's first doing a clean install.
[06:37.580 --> 06:43.380]  So it's removing all the previous files
[06:43.380 --> 06:46.420]  which resided in the documentary,
[06:46.420 --> 06:51.300]  so just removing all that was there.
[06:51.300 --> 06:53.700]  Then it's cloning the repository A, which
[06:53.700 --> 06:58.380]  is about to be synchronized into the checked out repository.
[06:58.380 --> 07:00.900]  In the next step, then it's removing the Git folders,
[07:00.900 --> 07:02.860]  then it's removing the readme files,
[07:02.860 --> 07:07.540]  and then it's creating the DocuSource sub directory,
[07:07.540 --> 07:12.420]  so either in the docs sub folder or in the community sub
[07:12.420 --> 07:20.580]  folder, with the target folder of the docs and the label.
[07:20.580 --> 07:26.500]  And then it's copying all those files from A to B.
[07:26.500 --> 07:30.820]  Then it's removing all the stuff,
[07:30.820 --> 07:33.900]  and then it's committing it directly to main.
[07:33.900 --> 07:36.260]  So there is no pull requests.
[07:36.260 --> 07:38.820]  It's pretty nice.
[07:38.820 --> 07:45.020]  And then it's doing this not parallel, but one after another.
[07:45.020 --> 07:50.940]  And then it's taking around about, for one repository,
[07:50.940 --> 07:52.700]  it's taking about 10 seconds currently,
[07:52.700 --> 07:58.580]  and the whole build process takes two minutes.
[07:58.580 --> 08:02.580]  And then there's the build workflow, which is just
[08:02.580 --> 08:07.420]  standard NPM CI, NPM build, and then it's
[08:07.420 --> 08:11.700]  being deployed to static server.
[08:11.700 --> 08:15.860]  And this is the result of it, our documentation page.
[08:15.860 --> 08:21.220]  Where you see on the left side the docs that are currently
[08:21.220 --> 08:23.380]  distilled in part of the SCS documentation.
[08:23.380 --> 08:26.020]  And this will, of course, grow because we're
[08:26.020 --> 08:29.260]  currently in the process of defining the standards
[08:29.260 --> 08:31.620]  and putting it all together.
[08:31.620 --> 08:36.260]  So there will be a lot more than in the future.
[08:36.260 --> 08:39.300]  Yeah, that's basically how we manage to do it.
[08:39.300 --> 08:41.580]  And if you have ideas, feedback, critics,
[08:41.580 --> 08:44.540]  then have a look at our repository.
[08:44.540 --> 08:47.340]  And we are meeting up in the SIG documentation,
[08:47.340 --> 08:49.260]  special institution documentation,
[08:49.260 --> 08:52.180]  every second Tuesday from 11 a.m.
[08:52.180 --> 08:55.860]  Central European time at, yeah, you
[08:55.860 --> 08:59.100]  can have a look at the docs.scs.community page,
[08:59.100 --> 09:02.460]  or scs.community page.
[09:02.460 --> 09:04.980]  And what is still to come, we're currently
[09:04.980 --> 09:08.580]  in the process of creating the whole framework.
[09:08.580 --> 09:11.780]  So we're structure-wise adapting towards the ATACS framework.
[09:11.780 --> 09:15.260]  You might know it's, yeah, I wouldn't call it framework,
[09:15.260 --> 09:17.420]  but it's more like a tax on me for writing
[09:17.420 --> 09:20.820]  excellent documentation.
[09:20.820 --> 09:23.660]  And currently, the workflows are triggered manually.
[09:23.660 --> 09:27.220]  And, yeah, it's soon to be automated fully.
[09:27.220 --> 09:29.380]  And there will also be an interactive overview
[09:29.380 --> 09:32.300]  about the whole standards, which worked out currently
[09:32.300 --> 09:34.780]  within the sovereign cloud stack community.
[09:34.780 --> 09:37.100]  And there will be a fancy community space, which
[09:37.100 --> 09:39.260]  is currently also in development.
[09:39.260 --> 09:41.460]  Yeah, join our metrics channel.
[09:41.460 --> 09:44.460]  And thank you very much.
[09:44.460 --> 09:54.460]  Thank you.
[09:54.460 --> 09:55.140]  Questions?
[09:55.140 --> 09:57.180]  Ah, here we go.
[09:57.180 --> 10:00.780]  Do you do releases of SCS?
[10:00.780 --> 10:02.260]  Yes, we do releases.
[10:02.260 --> 10:06.780]  OK, so how do you handle versions of documentations?
[10:06.780 --> 10:09.940]  We have, we can, if there will be a new version,
[10:09.940 --> 10:15.060]  we will use the versioning tool of DocuSaurus,
[10:15.060 --> 10:19.140]  which is basically a command line command.
[10:19.140 --> 10:24.780]  And then it packets all files and folders that is currently
[10:24.780 --> 10:28.940]  there and puts it into a version directory, basically.
[10:28.940 --> 10:31.420]  And then, yeah.
[10:31.420 --> 10:33.820]  There's no separate versions.
[10:33.820 --> 10:36.260]  So there are no separate versions on the website
[10:36.260 --> 10:38.020]  for the documentation.
[10:38.020 --> 10:39.980]  It's just the latest, always, on the website.
[10:39.980 --> 10:43.700]  No, there will be, there will be a future different version
[10:43.700 --> 10:44.500]  on the website.
[10:44.500 --> 10:45.140]  OK.
[10:45.140 --> 10:46.420]  Yeah, currently it's the latest.
[10:46.420 --> 10:46.900]  Yeah.
[10:46.900 --> 10:47.400]  Yeah.
[10:54.700 --> 10:59.380]  No, there was a person first here.
[10:59.380 --> 11:00.700]  Thank you for this talk.
[11:00.700 --> 11:02.300]  It's very informative.
[11:02.300 --> 11:05.740]  So my question is, what was your documentation
[11:05.740 --> 11:10.980]  pain point that inspired you to say, hey, let's have a hackathon
[11:10.980 --> 11:13.860]  and let's put our documentation in DocuSaurus?
[11:13.860 --> 11:19.020]  And did you solve for those pain points using your workflow?
[11:19.020 --> 11:20.940]  Yeah, actually, thank you for the question.
[11:20.940 --> 11:24.300]  Actually, the hackathon was planned prior to this.
[11:24.300 --> 11:29.780]  So it was perfectly placed for us to solve this problem.
[11:29.780 --> 11:33.340]  And the biggest problem was that no vendor wanted
[11:33.340 --> 11:36.300]  to change anything with their existing documentation,
[11:36.300 --> 11:37.620]  so no metadata.
[11:37.620 --> 11:40.380]  And then the thing is, with this workflow,
[11:40.380 --> 11:46.660]  you don't have to manipulate the external organization's
[11:46.660 --> 11:48.940]  documentation, files, or folders.
[11:48.940 --> 11:53.980]  And you just can copy them, distill them, implement them,
[11:53.980 --> 11:59.740]  and have the navigational thing is only, yeah,
[11:59.740 --> 12:02.500]  we do it with an hour repository.
[12:02.500 --> 12:05.620]  So it's minimal invasive, basically.
[12:05.620 --> 12:08.980]  Were folks updating your documentation before?
[12:08.980 --> 12:10.100]  You changed platforms?
[12:12.860 --> 12:14.820]  I'm just not clear about what the problem was
[12:14.820 --> 12:16.860]  that was being solved.
[12:16.860 --> 12:18.860]  OK.
[12:18.860 --> 12:20.660]  Oh, thank you.
[12:20.660 --> 12:22.900]  Yeah, thank you for the talk as well.
[12:22.900 --> 12:25.620]  Just a question, what are your input files?
[12:25.620 --> 12:28.900]  I mean, documentation appears in several formats.
[12:28.900 --> 12:30.780]  For instance, it's part of C files,
[12:30.780 --> 12:33.340]  but you have to extract it into, I don't know,
[12:33.340 --> 12:35.660]  PDF or HTML or whatever.
[12:35.660 --> 12:38.260]  Yeah, we are only accepting markdown files.
[12:38.260 --> 12:38.760]  Oh.
[12:41.580 --> 12:45.260]  Yeah, and the problem was that you have different vendors.
[12:45.260 --> 12:50.140]  And for example, if you want to pull all those markdown files
[12:50.140 --> 12:53.180]  and throw it into one folder, then it's going to be a mess.
[12:56.220 --> 13:00.220]  But we want to curate how the docs is being built.
[13:00.220 --> 13:02.860]  So that's the nice thing with Docusaurus.
[13:02.860 --> 13:06.660]  You can define within the sidebars
[13:06.660 --> 13:09.820]  how your whole navigation is being built.
[13:09.820 --> 13:14.300]  So you don't have metadata like lying directly
[13:14.300 --> 13:17.540]  in the vendor's target repository with the individual
[13:17.540 --> 13:18.260]  documentation.
[13:18.260 --> 13:26.940]  OK, so any more questions?
[13:34.460 --> 13:37.180]  Hey, do you plan to support any other documentation
[13:37.180 --> 13:40.940]  formats like Ask a Doc or R-Text or something like that?
[13:40.940 --> 13:43.140]  You know, like Sphinx is using Ask a Doc, for example,
[13:43.140 --> 13:46.820]  or more actual, or is it a restructuring text?
[13:46.820 --> 13:49.300]  Yeah, currently not.
[13:49.300 --> 13:52.660]  But it would be possible to convert it
[13:52.660 --> 13:54.180]  in a separate workflow.
[13:54.180 --> 13:56.180]  OK.
[13:56.180 --> 13:58.940]  But also, we use markdown because there's also
[13:58.940 --> 14:05.340]  a markdown linting process that's refining everything.
[14:10.020 --> 14:10.740]  Any more ideas?
[14:13.340 --> 14:13.940]  OK.
[14:13.940 --> 14:15.100]  Yeah, thank you very much.
[14:15.100 --> 14:17.100]  OK.
[14:17.100 --> 14:18.100]  OK.
[14:18.100 --> 14:19.100]  OK.
[14:19.100 --> 14:21.100]  Thank you.
[14:21.100 --> 14:23.100]  Thank you.