We are starting with the first talk in the Sovereign Cloud
Dev Room, and it's my great pleasure
to open the stage for Max, who's going
to elaborate on how he created a documentation framework
for the Sovereign Cloud Stack.
Enjoy.
Have fun.
Thank you very much.
Hi, everybody.
Thank you.
How did we create a documentation framework
that works across a group of vendors in the Sovereign Cloud
Stack community?
This I will show you.
My name is Max.
I'm knowledge management engineer at the Sovereign Cloud
Stack, and my background is broadly in web development.
The talk, TLDR, what is it?
Basically, it's a set of GitHub Action Workflows
to copy, mark, down folders and files from many As
to one single B. And once that's done,
B is being built into a single-page application
resulting in the Sovereign Cloud Stack documentation
at docs.scs.community.
And here, pull out your mobile phones and have a look at it.
And I will now elaborate what's behind this.
So what is the Sovereign Cloud Stack?
The Sovereign Cloud Stack combines the best of cloud
computing in one unified standard.
And SCS is built back and operated
by an active open source committee worldwide.
Yeah.
This is the SCS stack, and it's made up from many modules.
And yeah, it's quite complex.
And there is, yeah, of course, documentation,
but it's heavily distributed at different places
on the internet.
And that's quite difficult to keep track on.
Where do I have to go?
Where I have to be routed as an integrator developer.
That's quite a challenge.
So as an integrator and operator,
you have to manage different documentations
in different Git repositories and different docs.
And it would be nice to have them within one platform
to search and to have guides and tutorials and references.
And a great DX or UX.
But how could you do this?
This was my challenge.
And the aim and requirements for the documentation
is it has to be like a minimal rule
set where the approval is basically a no-brainer.
And all doc files will reside in one place.
And it must be, and this is probably the biggest challenge,
a low entry hurdle for companies with existing repositories.
Because no one wants to change the whole documentation
if it's being consumed by another stack, basically.
So no one has to make any major changes.
And then we were thinking about,
could it be made up with Git sub-modules?
And no, this is too complex to manage.
And Git subtree was then, OK, this could be nice.
But actually, it's not cool, too.
And then other vendors said, no, we
don't want to change anything in our existing repositories.
So then we had a great community hackathon in Cologne
in November 22, hosted by Plus Server,
where we have developed an eight-hour straight
in a tunnel working prototype with a custom GitHub
actions workflow or combination of this.
And this is one of the great things
with the sovereign cloud stack community
that everyone is joining forces to actually elaborate
on the common challenges.
So yeah, thanks also.
Shout out to Ramona and Tim, who worked on this prototype
with me on this day from OSISM.
Yeah, so how does it work?
Basically, it's GitHub actions workflow.
It's actually three workflows, as you see here.
And the whole concept is it's a Docusaurus React-based static
site generator.
You may have heard of.
It's outsourced by Meta.
And the three action workflows are
divided in collecting all the different documentation files,
then distilling them, that you only
have the markdown files from the repository,
and then it's being built and deployed.
Let's jump into how this works.
We defined docs.package.json, where
you define which doc files you need,
from which organizations repositories.
So basically, it's a package manager for docs.
So in the first line, you have the repo with the organization.
So sovereign cloud stack slash docs is the first one.
And then you define the source directory,
where the docs files reside in, or the folder.
The next line is then you define the target,
where should it be placed in the site.
Currently, there's a community page and a docs page,
docs for technical documentation, the community page
for how we organize in the community,
and also a contributors guide.
And the label is then how it should reside in the navigation.
Then the first workflow is reading the JSON,
and then defining a matrix strategy within GitHub Actions.
So for each element in the docs JSON,
a workflow is being run.
So this is the whole synchronizing and distilling
workflow.
We call it distilling, because it's
like in a distilling process, refining what has to be done.
And all the source code, because most of the time,
there's the source code, and then in one doc folder,
or docs folder, there is all the documentation
which we want, the other source files we don't want.
So we're distilling it.
So we'll quickly go through the workflow.
The first one is checking out the repository
with Secrets action token.
Then it's first doing a clean install.
So it's removing all the previous files
which resided in the documentary,
so just removing all that was there.
Then it's cloning the repository A, which
is about to be synchronized into the checked out repository.
In the next step, then it's removing the Git folders,
then it's removing the readme files,
and then it's creating the DocuSource sub directory,
so either in the docs sub folder or in the community sub
folder, with the target folder of the docs and the label.
And then it's copying all those files from A to B.
Then it's removing all the stuff,
and then it's committing it directly to main.
So there is no pull requests.
It's pretty nice.
And then it's doing this not parallel, but one after another.
And then it's taking around about, for one repository,
it's taking about 10 seconds currently,
and the whole build process takes two minutes.
And then there's the build workflow, which is just
standard NPM CI, NPM build, and then it's
being deployed to static server.
And this is the result of it, our documentation page.
Where you see on the left side the docs that are currently
distilled in part of the SCS documentation.
And this will, of course, grow because we're
currently in the process of defining the standards
and putting it all together.
So there will be a lot more than in the future.
Yeah, that's basically how we manage to do it.
And if you have ideas, feedback, critics,
then have a look at our repository.
And we are meeting up in the SIG documentation,
special institution documentation,
every second Tuesday from 11 a.m.
Central European time at, yeah, you
can have a look at the docs.scs.community page,
or scs.community page.
And what is still to come, we're currently
in the process of creating the whole framework.
So we're structure-wise adapting towards the ATACS framework.
You might know it's, yeah, I wouldn't call it framework,
but it's more like a tax on me for writing
excellent documentation.
And currently, the workflows are triggered manually.
And, yeah, it's soon to be automated fully.
And there will also be an interactive overview
about the whole standards, which worked out currently
within the sovereign cloud stack community.
And there will be a fancy community space, which
is currently also in development.
Yeah, join our metrics channel.
And thank you very much.
Thank you.
Questions?
Ah, here we go.
Do you do releases of SCS?
Yes, we do releases.
OK, so how do you handle versions of documentations?
We have, we can, if there will be a new version,
we will use the versioning tool of DocuSaurus,
which is basically a command line command.
And then it packets all files and folders that is currently
there and puts it into a version directory, basically.
And then, yeah.
There's no separate versions.
So there are no separate versions on the website
for the documentation.
It's just the latest, always, on the website.
No, there will be, there will be a future different version
on the website.
OK.
Yeah, currently it's the latest.
Yeah.
No, there was a person first here.
Thank you for this talk.
It's very informative.
So my question is, what was your documentation
pain point that inspired you to say, hey, let's have a hackathon
and let's put our documentation in DocuSaurus?
And did you solve for those pain points using your workflow?
Yeah, actually, thank you for the question.
Actually, the hackathon was planned prior to this.
So it was perfectly placed for us to solve this problem.
And the biggest problem was that no vendor wanted
to change anything with their existing documentation,
so no metadata.
And then the thing is, with this workflow,
you don't have to manipulate the external organization's
documentation, files, or folders.
And you just can copy them, distill them, implement them,
and have the navigational thing is only, yeah,
we do it with an hour repository.
So it's minimal invasive, basically.
Were folks updating your documentation before?
You changed platforms?
I'm just not clear about what the problem was
that was being solved.
OK.
Oh, thank you.
Yeah, thank you for the talk as well.
Just a question, what are your input files?
I mean, documentation appears in several formats.
For instance, it's part of C files,
but you have to extract it into, I don't know,
PDF or HTML or whatever.
Yeah, we are only accepting markdown files.
Oh.
Yeah, and the problem was that you have different vendors.
And for example, if you want to pull all those markdown files
and throw it into one folder, then it's going to be a mess.
But we want to curate how the docs is being built.
So that's the nice thing with Docusaurus.
You can define within the sidebars
how your whole navigation is being built.
So you don't have metadata like lying directly
in the vendor's target repository with the individual
documentation.
OK, so any more questions?
Hey, do you plan to support any other documentation
formats like Ask a Doc or R-Text or something like that?
You know, like Sphinx is using Ask a Doc, for example,
or more actual, or is it a restructuring text?
Yeah, currently not.
But it would be possible to convert it
in a separate workflow.
OK.
But also, we use markdown because there's also
a markdown linting process that's refining everything.
Any more ideas?
OK.
Yeah, thank you very much.
OK.
Thank you.