Val Grimm - Sovereign Docs ![rw-book-cover](https://img.youtube.com/vi/H7JK-dEQx-Q/maxresdefault.jpg) ## Metadata - Author: [[YouTube]] - Full Title: Val Grimm - Sovereign Docs - Category: #articles - Document Tags: [[video-notes]] [[youtube]] - Summary: Val Grimm - Sovereign docs - URL: https://www.youtube.com/watch?v=H7JK-dEQx-Q So the next talk that we're having um is by Val Grim and Val has done about 10 years of tech writing. And what I've certainly noticed is that during that 10 years, Val is very good at thinking deeply at stepping back from immediate detail and just coming up with what are the shapes and patterns of things. And from what I can understand of this talk, this is exactly that kind of thing where you started doing something and then you realized that you were doing something bigger and more complicated. In this particular case, the talk is called Sovereign Docs. And can I also request that you use the Q&A QR codes which are up everywhere so that I've got lots of interesting questions to ask Val after the talk. So, hit it Val. All right. Hello folks. Thank you for joining for this talk today. Um, so I was last in front of some of you in 2018. I'm very happy to see a lot of new faces as well as some faces I know from before. This is a slide from my talk in 2018. It is a reference to a terrible American television show called Highlander. The important thing is that it had a tagline there can be only one. And my point at that time was as many of us are solar writers uh writers on our own. There cannot be only one. And I hadn't had that experience a lot. But now in 2025, I can tell you it can happen. I'm very happy about that. So at least I can prove that it's possible. Uh even if I'm surrounded by developers and product and folks who are supportive and not writers, I'll take it. So very briefly I will give you uh I do a bit of expectation management explain why I am giving this talk and here um mentioned docs as code if folks have not met that before. Um this relates to containers and the very important and interesting bit is when I talk about um reframing the technology because containers are a technology but you have a way to think about the technology the technology is not just an end in itself and then of course the meat of this sovereign stack and how to get there as I said this is highle guidance this is not a tutorial This is not a map. These are some ideas. Uh because the point of this is when you're a less technical person and you want to make an argument for things to change to people who are more technical, you need to have the right vocabulary and the right way to talk. And something like this begins to give you your speaking points. So, it's not just about the philosophy, but about giving you some tools to go out there in the world with uh and fight for what you think is important. Um, as for why I'm doing this, I promise you I do not work for the EU. I am not arguing for EU regulation. Um, I just think working together is the only way we can achieve anything. Um and the way we work together is by gaining a common base of knowledge and realizing there are too many things we cannot solve on our own. The previous talk also had a lot of points to make about that. And as for why I'm doing it here as in the previous talk which I really enjoyed tremendously um this is a place where we can talk about tools but it's about much more than tools. So why sovereign data? This is a a topic that may be familiar to a bunch of folks here. Uh so bear with me. Um so the idea behind sovereign data, let's say here in Europe, is to bring data back within our borders and back within um providers that are not affected by things say like the cloud act. So the cloud act essentially means um when you use American services like say an AWS and if they have a European subsidiary say in France um if the US government wants to get a hold of your data they can even though it's a separate unit because the mothership is over in the states. So you have laws that reach across borders and of course surveillance is default. Um, the name Edward Snowden might mean something to a few of you. Um, it's also in conflict with European privacy legislation such as GDPR, which is the General Data Protection Regulation. I know it's a lot of jargon. I recommend googling a bunch of this after the talk if it's not familiar. It's fine to not know it. I know it from living in it. So um another reason why you might think about sovereign data and this is in the more general sense right thinking about having control over your data and understanding the tools you're using and the way you put it out there is it's all well and good when we're making choices about what we want to do with LLMs with our docs but when other people are grabbing our content and doing stuff with it and we did not authorize it this is a problem. So we need to have security for our docs and control over our docs. And if you're working with say internal documentation which is sensitive and then you still have to expose it over networks or over the web security is a concern. Getting back to the geopolitical um the trade situation, things like um price rises due to all kinds of factors as well as export controls that might cut off access to your tools. These are real concerns. Um, also for something that's very recent, I think it was last week, um, even here in Europe and many other places around the world, uh, we were affected by something called a control plane going down in one of Amazon's eastern data centers. Uh so even when you're running a European application on a European cloud, we're all dependent on this one little spot and I think it was uh Virginia uh in the United States approximately where that red dot is. Um of course that's honestly not just a problem. That's also a problem I think for folks in the states frankly. So now I have a lot of focus on Europe when we're a tiny part of a very large world. Well, it is where I'm standing here in Berlin. Uh, my employer is also based in Antworp, Claudio. And although you can tell probably from my accent, which is extremely American, I am originally from the States, Ohio, and Massachusetts, uh, I am now a Belgian citizen. So, it makes sense to me that I'm talking about Europe. Uh, about Belgium. Um, probably what a lot of people will think about when they hear about Belgium is Belgian waffles. There is no such thing. There are at least three kinds of waffles in Belgium. At least three. Uh, this kind is disgusting. I'm just warning you if you ever visit us. It's truly it's it's the taste of evil. So, as I mentioned, why am I talking about Europe? This topic is relevant all all over the world. The thing is it looks different in different places. We share common threats, but you your approach needs to depend on where you are. But this is not unique to Europe. I'm talking from a stage in Europe. I'm talking from the knowledge I have, but it's not unique. Uh, okay. So, this is another little excerpt from my talk in 2018. Um, my slides from 2018 are painfully ugly, but I am facing up to my ugliness. Um, so this is essentially a workflow. So I have to talk to you a little bit about authoring before I can talk to you about publishing that release step. So docsis code essentially this is pretty old. Um, essentially the idea is you author and manage docs with the same tools as you manage your codes. So basically source control um making pull requests. So in other words reviewing docs in the same way that you review code um and writing at least in text files um the way you write code. So that's pretty much as you do code. The thing is what if the docs what if you write docs like code? Well, you know what if you could publish docs like code because we ship applications to all kinds of platforms and containers. So what if we could ship docs and containers? This talk is not about that. I did that talk last year. Don't worry, the slides are available. Essentially short version on containers. Um these have been a popular way to deploy applications for about 15 years. Um it's really good if you want to roll out very quickly uh new versions of software and stuff like that. Also, dependencies are agony and they're really great for packaging dependencies with the application. And as I said, go on my LinkedIn, my slides that go into more detail about containers are there. Note devs, hold your noses. Um, so quick reason why I'm actually giving this talk now and why I gave it last year. Um so our project we had a very special case where we had multiple components which each had their own repository to avoid car crashes. We also had a separate docs repository for each of these that was very carefully thought out. Um different teams were developing each component which were also independently versioned. Not all of these components went to all of the platforms. Oh yeah, the platforms were at least three different kinds of cloud and aircraft installations and we needed to support both local preview and remote preview um and testing your containers locally in this case. So that's very special situation which is how we ended up with a very special solution. Um so our static site generator was MK docs. We have other tools. The top two are about binding together our zillions of repos and the one on the bottom right is about rendering them. So we would render the doc and put it in a container. I'm rewinding to the why to a thing that is now relevant which is another why why clario the company where I work. So the thing is everything I'm talking about in this talk including the philosoph philosophical stuff really winds into claudio. We make development platforms and data platforms. We use Foss. The platforms are based on Kubernetes. So everything I'm talking about here is just what we do. This is not about sales. This is I am not talking BS. This is real. So when we talk about publishing containers, there's a set of things that you need. Um so let's for example say a collaboration space. I should give you another second to read this. So collaboration space with source control, CI/CD, container management, container registry, vulnerability scanner and hosting. Now I will explain what these things are. You probably know what I mean by cont collaboration space. So something like GitHub, you have repositories, you can write, you can do reviews, you can save multiple versions of things and then you can hook that up to the next thing I talk about which is CI/CD. and CI is more on the validation side and housekeeping on when you're still in the repository. Um although for example you merge a pull request, it'll go through there. And then CD for example is more about I talked about containers. We need to build our container. We need to make sure that our container will run. That's more what CD does. This is skating thinly over the surface because I have half an hour. Uh but these slides will also be available online. It seems that I have not broken the habit of having verbose sides but I think I have gotten slightly less terrible. Oh dear, I seem to have a problem with the title here. Uh and then the next thing and this is really critical on the container side is a container management tool. I will give some examples later. So you need to build your container. That's what I mean by packaging. You need to be able to deploy it and you need to be able to take it away so that you can put something new there. You also need to run them. So you need a runtime. And when you have lots of containers as you can imagine uh there is a lot of hering to do. So it is the difference between having one goat and a herd of goats. Uh a container registry is as I said a warehouse for your containers. You can keep multiple versions of them. uh and also check to see if any of the dependencies in them for example have vulnerabilities. So a vulnerability is essentially something where someone can um exploit a weakness in software you're depending on. There have been some really uh noticeable ones recently but I think they always are. Um and so basically this is a tool that will look at public registries, proprietary registries for issues that people have reported. So like when people report zero days, that's where they go. Um, and so this is a tool that checks what you have against those lists and says, "Excuse me, you have something that appears in this list and you need to fix it." Lastly, hosting. I think a lot of folks will know what this is. My favorite line, the cloud is just someone else's computer. So it's a server connected to the internet. The term that might be new to folks is platform as a service. So this is something like if you want a database, you do not have to set up your database. They will set it up for you. Um so those are and that's just one of the many kinds of services they offer. Right? The idea behind this uh this pass thing is that you want to be focused on building your application and delivering your application and you do not want to be dealing with the infrastructure underneath it because that takes time and it takes people. So back to containers themselves. I had lots of arguments about yeah why containers are great. This is mostly the slide from my previous talk. The key thing here is that they're portable. And a lot of times when people think about what's nice about containers being portable is they say, "Ah, I can take it to Google Cloud. I can take it to AWS. I can take it to Azure. I can put it lots of different places." But from working with the air gout situations, um, I started thinking about, and I think this is probably a pretty American phrase, what if portability means we could take our toys and go home? So, by taking our toys and go home, I mean, of course, taking back control of our data. So, I'm going to give you a little bit of a recipe. Um, except this is not a recipe that you have to follow precisely. It is definitely I am not being a baker here. You do not need precise amounts before some kind of pancake explodes. Um, but it's like here are some options for how to build a sovereign stack. So, we've talked about docsis code and portable publishing. Um, the next things I will talk about is choosing free and open- source software. That's what foss means. I mentioned it earlier. uh and selecting hosting. By the way, I know that stack is not quite the right word here. Um but part one, some of it is a stack, some of it is a tool chain. Sovereign stack sounds really nice. So, let me be terrible. So, free and open source software. Open means you can read the source code. Free means two different things, which is why sometimes people use the word libé. Um, it means you can make your own derivatives and you do not have to pay for it. But it is also because it's free maintained by volunteers. I'll get back to that in a moment. So where I work at Claudio, we have a whole confluence page about how do we choose the free and open source software that we use. This is an extremely short version of that page. So is there any documentation? We can't take that for granted. I think any of us that has worked with it would know this. On the VLC page, there's just we have given up. Not quite that, but it's very similar. I felt very bad because I use it a lot, but I'm not up to it. Uh, Provenence, is this what it says it is? And has it been compromised in some weird way? That's a short version. Um, maybe you've heard about supply chain attacks. It's where people will get in and compromise packages uh open source. So, good to know. vitality. If there's like one guy maintaining this and five people using it in 10 years, this might be a bad thing to be using. Um, and lastly, the code evaluation. Is it safe? Is it fragile? This kind of thing. So, about FOS, just a side note, working for free is very much of a luxury. As you can see um these big American companies in things like say the CNCF or the Linux Foundation may have a lot of power. This is also true with individual open source projects where they get involved and that means they get to drive a lot of the decision-m this is also true for example in the context of non-governmental organizations or nonprofits. It's really dangerous to have one really big funer because they start to be able to call the shots. And so the thing is one of the ways around this is to build alternative models. So for example, if you're using your company, a company that makes money, is using software that does not cost money but is made by people with their time that they are giving away for free. It might be nice to also put some money in there. It's called the free writer problem. So there are also governmental problems, other models. I'm just saying if I'm going to talk about free and open source software, I'm going to talk about funding free and open source software. So now I'll get into the stack itself. Um, so I mentioned NOS's or non-governmental organizations, nonprofits. These are not the tools I'm talking about because that's not most of my audience here. There are some special options, I'll mention Codeberg later, that are really intended for those kinds of projects. So collaboration space um actually at Claudio we do use gi um a lot of these options are self-hosted um Forgejo is which I might be mispronouncing is used by codeberg who I'll mention later um which is that does provide a hosted solution but it's not actually intended for companies more on that in a moment uh gitlab you can use uh self-hosted and there are some options. Actually, I'll jump to my next slide. So, GitLab, there is third party hosting. It's worthwhile knowing that there's an American parent company, but I don't think that's necessarily an issue. It's just good to know. Gy, they have a cloud solution, but the locations of their cloud are not really clear from their website and their communications. So, it's good to know. I know that self-hosting is not everyone's favorite thing. It might be worth looking around to see if there are there is hosting over here that also offers an add-on like this. I will mention Source Hut. It is definitely hosted. It is definitely unusual. Um, it's similar to the way people developed the Linux kernel. You have to send emails with patches. So, I suppose for some folks who have never used a GitHub, it might be more familiar, but it's unusual and I know the guy. That's the way I know about it. Well, that's not the only reason. So, the reason I'm not mentioning codeberg is as I said, uh they don't really allow closed repos. It's intended for free and open source software projects, not companies. Now, when we come to CI/CD, there is a plugin for gate. Uh but that's really more the CI side. We've been using Flux um although I think that might be on the process of becoming orphaned. Um, Codeberg itself uses Woodpecker and Semaphore is a small Serbian company that has open sourced its solution and you're allowed to fork it. So, you have four different options that are worth exploring. Um, now I will actually get to the containers part. Um, this is a whole deep topic and I recommend if you're curious about containers also looking into some training. Uh, the Linux Foundation has u a free option. There's some other options. So Docker and Podman are things you can use to build containers and run containers. So Docker is its own company. Podman is something that was put together by Red Hat. There are a lot of similarities. There are a lot of differences. I won't go into it. The point is you don't only have Docker. You have options. Every of these every one of these tools I talk about, I'm giving you more than one option. Um and then when you come to container management because uh container tools um are also things you can use to manage containers. Um you also have options for building smaller clusters. Let's say if you have one or two containers for your docs then you can use something like a kayen cluster or mini cube. For example, mini cube. If you take the um Kubernetes training from the Linux Foundation, they'll have you set up a local mini cube. So you can get the experience of working with Kubernetes without this gigantic sprawling cluster. Um so these are if you really want to begin to try out things with containers, um this is a good place to go, good thing to try installing now. when you get to really large clusters, um folks have also been known to use um in addition to Kubernetes uh tools like for example Rancher which is associated with Souza um which the Germans in the room may recognize um and that provides some sort of more userfriendly options for when you're managing a really large cluster worth looking into. Uh you also have a couple of container registry options. Uh at Cladio we've used results. Um it seems to have worked reasonably well. Um Harbor is also it's it's worth like reading deeply into each of these and seeing what actually meets your needs. Um and then when we come to vulnerability scanners um we've we've used Trivia. I think we looked at Nuclei and Trivy is specifically uh intended for cloud environments. That's why you're seeing that thing that looks like a package. Um and essentially I'd say the way to think about this is the way to think about any tool. You need to look for something that's suitable for the amount of expertise you have around uh to help you run it. Um and this is not always a trivial setup. Let's put it that way. Now I will get to the bit probably a lot of folks thought about when they heard the name of this talk which is hosting. So um I've said the word hyperscalers a lot in the last couple of weeks and I usually get a what what is a hyperscaler? So um you may recognize these icons over on the right. Those are some of the most popular hosting options. All of them are hyperscalers. You have Google Cloud, AWS, and that blue thing is Azure. And so these hyperscalers, you notice these three are all these big American companies. So they're all vulnerable. Uh whenever you use any of them, even if you're on a European site and subsidiary, your data is vulnerable to the cloud act. So the thing is, do you need a hyperscaler for content delivery networks? So you can get content to a variety of different places in the world? No. Certificates? No. Open source tools like the ones I talked about? No. So there are negatives. You can see I have a pretty long list. A lot of it rolls down to vendor lockin uh and cost and difficulty getting a hold of a human as you might imagine with a really giant company. Um the difference is a lot of people may have certifications in that. It can be quick to roll out, can be easy for nontechnical people with hyperscaler alternatives like stuff here in Europe. Um may not so far because the options are growing have cutting cutting edge tech. It might not have as many features yet, but it is safe from the cloud act. If it's smaller, you might get to talk to a human and have more options to set up things the way you like and most importantly not pay for what you don't need. So I'm going to cover two smaller options and two bigger options. So Exoscale is the smallest of all of these and there they have sort of a more bare bones basic option if you're really like I want full control. I want to do this the way I want to do this. Not really any frills. Clever Cloud um is a French company and they have more of those kind of add-ons like a MongoDB stuff like that. Uh when it comes to larger companies uh that lovely pink logo there might that pink color might look familiar because Open Telecom is Deutsche Telecom. OVHC cloud is a French option. Both of those have been around a bit longer than Exocale and Clever Cloud. It's a question of choosing what's suitable for your needs. So I've covered that whole package. writing, publishing, what do we need to publish with and where are we going to put it? Now, this is the same thing I ended up with in my previous talk, which is we found an awesome tool. We found an awesome something. How do we do it? A lot of these talks have how the previous talk had how because you're facing the guy who cares about the money. How is this going to hurt me in the money? Is it worth investing in all of these changes? You can also be just at sea in the tech and like how do I make decisions about this? How do I find people to help? This is also a slide from 2018. Um, and it's all about finding allies. It's all about seeing where your incentives or where your needs line up with the needs of people in other departments. The job of a tech writer is to run toward the screaming. And the screaming may also be where you will find your help. So that's continues to be my advice. As I said earlier in the talk, we cannot get anywhere if we do not go there together. But it's amazing where we can get when we go there together. On that note, I'm very thankful to my reviewers and all of my colleagues who have supported me in this um and to all of you. You're a wonderful community. Okay. Okay. Well, that was great. So, um I would like to encourage people to add more questions to the slide out. We have some, but I'd love to hear more. Um yes, that was fabulous. Thank you so much, Val. Um I did have one question on my own batt, which is that I am not actually off of with the cloud act and what it is. >> Okay. >> What is it? Well, it's as I said, it's so the thing is the idea is and there have been there's another cutout like this that I can't remember the name of right now. Um, so American companies want one thing. >> Yep. >> European regulators sort of want another thing because of course as always relationships between governments and lobbyists are always kind of interesting. And so Europe will bring in this powerful privacy legislation and then you have to find cutouts and ways around it >> um for the services folks want to use. And so you know it's it's not fair to call it an arms race, but it's like we have GDPR, you have the cloud act, we're bringing in the cyber resilience um oh lord CRA, whatever the A is. Thank you. Cyber Resilience Act and God knows what will come next. And as far as I know, it's not going to kill Foss, by the way, which is good. But yeah, so I don't think I've really answered that. I went a little off piece, but >> thanks. I just wanted a bit more mental model of it. >> Yeah, the big picture, it's feels like a privacy arms race. >> Yep. Okay, fair. Um so one of the questions that I'm particularly interested in from the um from the the queries is doesn't encryption essentially nullify the risk from cloud act related data seizure in the same way that you know they can have your iPhone but they can't unlock it. So the thing is the kinds of re I would say that is how do I put it? It sounds great. The problem is the amount of computing power the NSA has and is increasingly having and all these advances toward quantum computing and stuff. I want to believe that this is enough. But in my gut of guts, if it's my private stuff, I don't care. I still feel unsafe. But that's me >> and I don't think I'm alone in that. If it's your trade secrets that your company needs to continue to function, >> how thin of a membrane are you comfortable with? And do we even know how thin the membrane is? I am not a cyber security researcher, but a lot of them seem to be sweating. >> Fair. Good point. Um, some more technical questions that are quite interesting. What would be the use case? Oh, for using more than one container for documentation or even going for a cluster. Are there ways that >> um the person then says thinking about statically generated pages? >> Well, I think it depends very much on your application. In our case, we wanted to combine um all of our manuals into one site, although we would have, you know, the set of manuals that we would ship would depend on what was on the platform, right? Um, but let's say for example your manuals are much bigger than ours were and you instead of wanting to say bind everything into one container, you want to have a cluster where they're all sitting next to each other. That's one way I could see people using it. But again, I think that's the beauty of containers. You have this tremendously flexible solution that you can shape to what you need. That's the whole idea. That's the whole philosophy of this talk. Go for the freedom to make the choices you want to make where you have control over your content and you have control over how it's getting out into the world. Okay. Um so when you're looking at the various choices that you make, um what are some good sources for checking out the funding of and control of innocuous looking um tools? Well, I'm not sure I can say that specifically about tools right now off the top of my head, but I very recently looked at a we'll say organizations because that's something I looked at recently and I will not name many, but the thing about nonprofits um some of them is that they will list things like a board of directors or a board of advisors or something like that. And you may also see this for sometimes for the way that open source packages are funded also. Sometimes there'll be an umbrella organization and you'll fund that and then things will trickle here and there and wherever. Um, so I would say it's sometimes it's opaque and it takes the journalist who knows what they're doing. >> And sometimes it is simple as I go to their website, I click on who their board of overseers are, I count the I count >> Yeah. Yeah. >> who's from where and Yeah. >> Yes. So a sort of a broadscale question. Um if these are public docs, what sort of use cases do you have for them anyway? >> For public docs. >> Yeah. Is there a use case for public docs or is it simply the the the docs that you've been working with that are more? >> So our docs were very definitely not public. >> Fair. >> Um very extremely. That is why some of the places they would go are airgapped. >> Yes. Um I figured that. >> So the thing is I think it really depends. Um there I think that there are security implications including when it comes to LLMs and things that I cannot account for. There must be things that I cannot account for. But I certainly know for when you want things to be private and also actually someone told me a story recently um about their translation agency had all of the content. um they had a tool they'd put it into and then it went to the translation agency and they had a limited local backup and the translation agency went voom >> and their content left with it >> point. >> So I guess that's also an argument with public docs again it's all about control over your data. Yeah, >> backups. I was astonished how like non-obvious backups seem to be like, "Oh, yes, we have a backup file server. It's in the same closet as the other file server." And then there was a fire. >> Yeah. So, uh, we have run out of time. This was a fascinating talk from a completely different angle than a lot of the other talks. So, thank you so much for bringing this to the party. Um, very good job. Can we have a round of applause for Val?, Val Grimm - Sovereign Docs, YouTube, 01k9d0b9t1wqp2tk06v58xwem2.