How we created a Documentation Framework that works across a group of vendors in the sovereign cloud stack community
This is a modal window.
Das Video konnte nicht geladen werden, da entweder ein Server- oder Netzwerkfehler auftrat oder das Format nicht unterstützt wird.
Formale Metadaten
| Titel |
| |
| Serientitel | ||
| Anzahl der Teile | 542 | |
| Autor | ||
| Lizenz | CC-Namensnennung 2.0 Belgien: Sie dürfen das Werk bzw. den Inhalt zu jedem legalen Zweck nutzen, verändern und in unveränderter oder veränderter Form vervielfältigen, verbreiten und öffentlich zugänglich machen, sofern Sie den Namen des Autors/Rechteinhabers in der von ihm festgelegten Weise nennen. | |
| Identifikatoren | 10.5446/61659 (DOI) | |
| Herausgeber | ||
| Erscheinungsjahr | ||
| Sprache |
Inhaltliche Metadaten
| Fachgebiet | ||
| Genre | ||
| Abstract |
|
00:00
Architektur <Informatik>InformationGruppenkeimFramework <Informatik>GruppenoperationWeb-SeiteQuellcodeCloud ComputingModul <Datentyp>RechenwerkSystemplattformNichtlinearer OperatorBimodulFramework <Informatik>GruppenoperationKartesische KoordinatenDatenverwaltungDokumentenserverElektronischer ProgrammführerWeg <Topologie>Web-SeiteEinfache GenauigkeitElektronische PublikationSoftwareentwicklerInternetworkingSchaltnetzSchnittmengeWeb-DesignerFlächeninhaltOpen SourceSystemplattformMAPDifferenteSchlussregelCloud ComputingMathematikComputeranimation
03:22
PrototypingGruppenoperationWeb SiteGebäude <Mathematik>BewegungsunschärfeWeb-SeiteVerzeichnisdienstWurzel <Mathematik>IntelMatrizenrechnungStrategisches SpielFunktion <Mathematik>Metropolitan area networkParallele SchnittstelleMini-DiscKlon <Mathematik>Inhalt <Mathematik>QuellcodeRechenwerkImplementierungRückkopplungVollständiger VerbandDokumentenserverElektronische PublikationSelbst organisierendes SystemStrategisches SpielMatrizenrechnungQuellcodeVerzeichnisdienstWeb-SeitePrototypingWeb SiteDifferenteGruppenoperationMultiplikationsoperatorMeta-TagHydrostatikSchaltnetzStandardabweichungDokumentenserverForcingZweiInstallation <Informatik>MereologieServerProzess <Informatik>DatenverwaltungElement <Gruppentheorie>Open SourceGeradeToken-RingRepository <Informatik>Computeranimation
08:52
RückkopplungVollständiger VerbandDokumentenserverMatrizenrechnungDatenstrukturMinkowski-MetrikStandardabweichungInteraktives FernsehenImplementierungTextsystemProzess <Informatik>VersionsverwaltungWeb-SeiteDifferenteFramework <Informatik>Web SiteElektronische PublikationMetrisches SystemLokales MinimumDokumentenserverMetadatenDichte <Stochastik>Ein-AusgabeSelbst organisierendes SystemMereologieDateiformatAnpassung <Mathematik>PunktComputeranimation
14:22
ImplementierungComputeranimationFlussdiagramm
Transkript: Englisch(automatisch erzeugt)
00:05
We are starting with the first talk in the sovereign cloud deaf 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.
00:20
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 a knowledge management engineer at the sovereign cloud stack, and my background
00:42
is broadly in web development. Yeah, the talk, TLDR, what is it? Basically, it's a set of GitHub action workflows to copy markdown folders and files from many A's to one single B. And once that's done, B is being built into a single page application resulting
01:00
in the sovereign cloud stack documentation at docs.scs.community. And here, pull out your mobile phones and have a look at it. Yeah, 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,
01:21
and SCS is built, backed, and operated by an active open source committee worldwide. Yeah, and this is the SCS stack, and it's made up from many modules. And yeah, it's quite complex, and there is, yeah,
01:43
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 we have to go, where I have to be routed as an integrator, developer. That's quite a challenge.
02:01
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. Yeah, and a great DX or UX. But how could you do this?
02:23
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 probably the biggest challenge, a low entry
02:44
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're thinking about, could it be made up with Git submodules?
03:02
And no, it's too complex to manage. And Git subtree was then, OK, this could be nice, but actually it would, yeah, it's not cool to. And then other vendors said, no, we exist in repositories.
03:21
So then we had a great community hackathon in Cologne in November 22, hosted by PlusServer, where we have developed in eight hours straight in a tunnel a working prototype with a custom GitHub actions workflow or combination of this. And this is one of the great things with the sovereign cloud
03:41
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
04:02
from OSISM. So how does it work? Basically, it's GitHub actions and workflow. It's actually three workflows, as you see here. And the whole concept is it's a docosaurus react-based static site generator, you may have heard of.
04:22
It's open source 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.
04:42
Let's jump into how this works. And we defined docs.package.json, where you define which doc files you need from which organization's repositories. So basically, it's a package manager for docs. So in the first line, you have
05:01
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.
05:22
Docs for technical documentation, the community page for how we organize in a community, and also 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.
05:43
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 the distilling process,
06:01
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 file 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.
06:22
The first one is checking out. So checking out the repository with secrets, action token. And then it's first doing a clean install. So it's removing all the previous,
06:41
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,
07:01
then it's removing the readme files, and then it's creating the docu-source subdirectory. So either in the docs subfolder or in the community subfolder with the target folder of the docs and the label.
07:21
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,
07:42
not parallel, but one after another. And then it's taking, yeah, roundabout, for one repository, it's taking about 10 seconds currently. And the whole build process takes, yeah, two minutes. And then there's the build workflow,
08:01
which is just standard NPM CI, NPM build, and then it's being deployed to a 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
08:22
and part of the SCS documentation. And this will, of course, grow because we are 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 managed to do it. And if you have ideas, feedback, critics,
08:41
and then have a look at our repository. And we are meeting up in the SIG documentation, special interest group 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.
09:02
And what's still to come? We're currently in the process of creating the whole framework. So we're structure-wise adapting towards the ATAXIS 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
09:23
and, yeah, soon to be automated fully. And there will also be 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.
09:42
And thank you very much. Questions? Ah, here we go. Do you do releases of SCS?
10:01
Yes, we do releases. Okay, 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 package all files and folders
10:24
that is currently there and puts it into a version directory, basically. Yeah. So 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 a future different version
10:44
on the website. Okay. Yeah, currently it's the latest, yeah. No, there was a person first here. Thank you for this talk, it's very informative.
11:02
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 DocuSaurus, and did you solve for those pain points using your workflow? Yeah, actually, thank you for your question.
11:21
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
11:42
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 within our repository.
12:03
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. Okay.
12:20
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 where you have to extract it into, I don't know, PDF or HTML or whatever. Yeah, we are only accepting markdown files.
12:42
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. And so, but we want to curate how the docs is being built.
13:00
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.
13:25
Any more questions? Do you plan to support any other documentation formats like AsciiDoc or RText or something like that?
13:41
You know, like Sphinx is using AsciiDoc, for example. Or actually, you restructure text. Yeah, currently not, but it would be possible to convert it in a separate workflow. But also, we use markdown because there's also markdown linting process that's refining everything.
14:10
Any more ideas? Okay. Yeah, thank you very much.