NixOS Summer of Nix 2022 — Public Lecture Series, 9 Aug 2022

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Valentin Gagarin - Flattening the Learning Curve (SoN2022 - public lecture series)

Description

In this lecture, Valentin will talk to us about a long standing problem within the Nix community, documentation. Valentin will cover how we are flattening the learning curve, and how you can help.

Special thanks to the NLnet foundation, the European Commission, the NixOS Foundation, and Tweag for making this event a reality!

The continued discussion for the lecture series is happening over here:
https://matrix.to/#/#son2022-lectures:matrix.org

More information about the Summer of Nix can be found on the website:
https://summer.nixos.org

A

Hello, how is everybody doing today.

A

I hope my microphone is still working.

A

Yes, it should okay cool so welcome again to another lecture of the summer of next 2022 public lecture series. Today, we'll have valentin talk about flattening the learning curve and I think of some especially some experienced sneakers and people that go a little bit back into history for next documentation and the learning curve.

A

Nyx has always been a bit of a hot topic, so valentin has actually been working on this and he'll, introduce it like what he's been doing and how you guys can help actually, as well now before we get started this lecture, just as our mains lecture in the past was pre-recorded because valentine couldn't make it live just fine, but just for people that have questions you can still post them on youtube and linkedin and the own cast instance and I'll try and relay them into the into the matrix channel.

A

If you want to ask your questions directly into the matrix channel, that's also fine, because after the lecture, valentine will still try and see. If you can answer some of those questions on matrix, so know that the questions this time will be answered on matrix, just as with our main stock to keep the flow. However, we have included a very small portion of q, a from some internal colleagues and yes without further ado I'll I'll start.

A

The video, I won't, keep you guys waiting any longer so enjoy the video and I'll see you in a bit.

A

uh To the summer of next 2022 public lecture series this year, um I have heard that you're gonna talk to us about a little bit about the documentation and the learning curve of next next packages and and nexus.

B

Yeah exactly um so, my name is valentin. I work for tweak.

B

I joined tweak beginning of this year and the question was: what could I do as long as I don't have a client project that I can work on and tweak has this internal mix team, where we develop the product and help onboard our own co-workers working with next, because it's a daily, stable tool in the company um and well, I joined tweak as a mixer, because I, when I discovered the project that's a couple of years ago, I finally found something I was looking for for a long time, a tool to make computers work reliably in the long run and if you know nyx once you have built something, it will work reliably until you change it and not change.

B

Underneath your your feet. Without you intervening and as anyone who tried to approach the system knows, it's really hard to wrap your head around all the concepts that are inside it, starting with a mixed language or how how packages work internally, how nixos is configured.

A

B

You would work with multiple machines and well the learning curve. Anyone who has tried it. It really is proverbially steep. It takes a lot of time to really um truly grasp the thing uh well enough to be confident using it. So I probably took like two years before I was really confident packaging, a new software that was not yet in mixed packages, so.

A

That's that's faster than I was.

B

Well and um when I observed new colleagues joining tweak, who did not know nicks at all, I quickly found that we have to do something about it and I wondered what would that be um and luckily- or I'm really happy that um that tweak leadership allowed me to spend some time on this doing it properly. That's the other thing that I also observed when I was spending that time on my own and my free time.

B

um It simply turns out the problem is usually too big to attack it on your own, like if you spend a couple of hours here and there you may maybe make notes on your on your own or maybe fix a little typo here and there, but really changing anything about the big state of affairs. The big picture is essentially impossible: um the entire documentation um ecosystem and how things are interconnected and how they're presented it feels a lot like a jungle I would say, and so you would yeah so you would.

B

You essentially need to get everything of that in your head and then uh navigate through it more or less and um well so so I started essentially. So my presentation is a little bit ad hoc here, so.

A

This is my: um I will actually pull in your documentation, so yeah valentin will be talking about the documentation of nexus. If that isn't obvious just yet, um but um I look forward to watching it valentin.

B

Yeah, we will be.

A

Right in the sidelines, listening to you and watching you and we'll be right back at the end for questions. Okay,.

B

Yes, please interrupt me at any time because um well, it's just like a little chit chat about uh what's been going on in the past month,.

A

Sure your slides should not be visible. There we go.

B

Okay, so essentially, this is just my um internal project pitch a little bit made up for public viewing. This is also the same thing that I submitted to the summer of nix, because it's all the same concern like mix is really hard to get into, and maybe, if you have been around 2019 or so you have seen this little post on discourse which has adapted has been adapted to make s, um so I started figuring out what is actually the problem.

B

Why is it so hard to learn to use nyx, and I started with a little survey on my own intuition, um so one one thing that is very very prolific is ian henry's what he calls a let's play, but for obscure software documentation. I think it already says it all if you read it as like 40 parts or something it's essentially mocking how complicated nyx is set up and how confusing the documentation is often written, and I actually talked to him and asked him well. Why don't we change something about it?

B

That was a year ago or so, and the thing is: if you went through all these notes, it would result in like hundreds and hundreds of issues or pull requests against the documentation. As I said, this is nothing a regular person can do on their own or even in the spare time. um So what would be the most valuable thing, the most important thing that we could attack immediately, then I started just doing an overview, so what kind of data do we have?

B

We had this uh nyx survey in the beginning of the year, which essentially told us that a lot of people use nixos, roughly half of the survey participants and documentation is one of the most impressive problems that we have. I think ron summarize it as documentation, documentation, documentation.

B

um I also went through these survey results because there's a lot of them and helped um kind of sorting out all the all the numbers uh just to get an idea of. Where do people get stuck most, but that's still not enough because well, if you, um if you say well, flakes, are really complicated, understand how they, I don't understand, how they work or um if people say well, I want to use nixos, but it's really hard to get into, because the nick language is hard to learn that doesn't really help.

B

So I started doing user studies and observed new comers to tweak and some friends who haven't seen seen knicks yet to see where they stumble exactly and at the same time I had to know what kind of resources are they even in the ecosystem. So I did a little survey of resources on my own and wondered okay. What do we have?

B

There's one thing um called the documentation system, which kind of categorizes the types of uh documents from which people can learn how something works, and I try to just figure out what kind of categories do we have in the ecosystem right now and did a little survey? It's not entirely complete and meanwhile I have found a little bit more, but mostly we have a lot of tutorials for the nyx language.

B

Some introduction to nyx packages, which is mostly the mixed pills, but at a very low level, and not all that much about nixos. As far as I'm aware, there's no real overview on how mixers really works.

B

We have a bunch of uh how-to guides to solve actual problems, mostly those from nick's death and john ringer, who has been doing the talk last week also has some great introductions and also how to use nixo s, which is mostly in relation to deploying stuff and doing some configurations, but then the two other interesting things is what are the what's the reference material like? um How do we like, where are all the important aspects of nics, listed down to every detail, and this is fairly clearly structured?

B

Nixos has a manual next packages has a manual and mix itself has a manual, and actually it's split for the mix commands and the next language.

B

But if we dive deeper, it's actually uh both instructions and tutorials and a little bit of explanation here and there it's not really clear cut, but why nyx is that way and how it really works internally is only really explained in elko's page thesis, and this kind of make me made me wonder, is may that be the reason why people struggle understanding nick so much because that was I mean that is anecdotal still, because when I started um using mix the first thing that I've actually read was the thesis and by some incident exactly in that same year, disappeared from the front page of or from one of the pages of the nixa's website.

B

And since then, I've constantly had people complain like nix is too hard to understand it's hard to learn. I don't know how it works. I only copy paste code um and well not all of the people are crazy enough to actually read a 200 page via phd thesis, but the most important thing in this thesis is really how mix works in principle, and that is just that. The file system in nyx is considered to be used like the memory system in a programming language.

B

And that was the thing that hooked me most when I got into nix first that we could solve the entire problem of not just deploying but also building software.

B

If we um stop thinking in terms of files which have changing contents, which may just not be there or have been have be something else than we expected and just pretend that the dependencies that we have for building our software work just like pointers in a computer program, if we nail them down more properly, instead of just changing and writing onto them and moving them around freely. Without all that much discipline, then we would solve a ton of problems that we had in the past.

B

I don't know 40 years of open source software, so I kind of set myself on a well tefan called a crusade to help people learn mix in a more principled way and um okay. I said I already started doing these surveys and, while doing these surveys I found out and also talking to people a lot who had a lot more experience than mix than I did. I found out that.

B

Well, maybe it's not all that far-fetched or high level, as as I might think it turns out that people usually have much simpler problems which they already struggle with.

B

For example, um it doesn't really matter to people all that much how um how nicks works internally, whether it's a functional program, because most people who are interested in using x don't really care all that much about functional programming, they're, mostly practical developers, um and also they don't have time to go through all these concepts that I try to lay out when documenting the underlying architecture, like it's a ton of stuff that you have to read and understand, and even if it's sorted out a little bit better, it's still a jungle, it's still complicated because it's a well it's a system that essentially tries to reinvent how we would build and deploy software.

B

So what people really care about is well. How do I get things to run and that's that usually amounts to just typing nick's shell dash p and then finally right package name. um So the question was: how would we approach um how? How would we approach people who want to get things done with nics and still help them understand it well enough such that they can actually make use of it on their own at some point and navigate the jungle of documentation that we have, um and this is when things kind of turned around.

B

So my first idea was to well. Why don't we just write a book like the next book, which will explain how nyx works fundamentally and then show how you would use these fundamental concepts to build up something like a package but in a more concise way, in a more user-oriented way than we had, for example, with nyx pills, which people read as one of their first documents um when they get introduced into nyx and they'd get totally confused about the details, because they don't usually matter.

B

So. I wondered what if we did like a principled introduction to nyx and exercises and questionnaires and test it with people who really try to use nics and when it's actually started trying to test it with people who want to use nyx. It turns out they don't care all that much um and when I did my uh survey of existing material of course stumbled over nix.dev.

B

I don't I mean I didn't stumble over it, it's one of the most prominent resources that we have, because it has such well-designed, well-written, really concise, to-the-point tutorials, that I thought these should actually be the core of whatever that book would eventually become, um and the other thing was that we have this large collection of tutorials that are um compiled in the nexus wiki, and both resources are actually unofficial right.

B

So domin has this next.dev and had is going for many years now, um and the nexus vk as well is at least I don't know five years old, and none of these reasons are really official and the question was: how would we bring this combined knowledge together um to to make most use of it?

B

It's essentially a little bit like the same thing as mixed packages where mixed packages, as john said, is this huge collection of um of organizational and procedural knowledge of how to build packages and how to organize all these things together, and what we probably need is something like this: just for documentation, where we combine all the insights into how how people actually use nyx and how they what they need to make most effective use of it and how to approach it most effectively, and this is why I thought: well, let's just bring all of these people together and make something like a knicks documentation team.

B

um This is the nexus wiki. um What would you call these people? Someone? Somebody gave me a link to this thing where they call themselves documentarians and then I said well, let's just become mixed. Documentarians.

B

What would that entail? We would bring together all the information that we have in the ecosystem. All the people who write the interesting articles and the interesting tutorials and the reference material sit down together and figure out what would a new way of learning nics? What would a path on this journey into mastering the next ecosystem look like, so I did a bunch of um drafts and proposals. What that could be one. One of them would be okay, so assuming that this is how you land on the front page and see some examples.

B

What how how would you learn that?

B

What we already have is that the website points you uh to nickel dev tutorials, but it doesn't really say that they are nick.dev, but we should do that more explicitly and then not just start with the most simple use cases such as finding and running packages, but also explain the main features of the ecosystem, as it is right now right now, there's no real explanation of the difference between imperative and declarative package management right now.

B

We don't really have a really good introduction to the next configuration language and right now we don't really have a clear distinction of how developing software using x, packaging software for nics in the package, collection or managing your systems with mix how they really interact with each other.

B

We only have components of these things and, as I said, one person cannot really change the big picture, there's just too many moving parts, and this is why um this documentation team that we founded recently two months ago.

B

My vision for it is to kind of bring together all the expertise in the community and help help shape that future.

B

I wrote a little announcement, but really the point is easing nyx learning to the point that we have pathways into this jungle and pave more structured road systems, because the jungle won't go away. The, for example, the dichotomy between imperative and declarative package mansion. It doesn't go away because that's an integral part of nix. What also won't go away is um the old cli and the new cli, the non-flakes world and the flakes world, but we have to help people navigate these complexities.

B

um One of the distinguishing features of nyx is strong backwards, compatibility simply by the virtue of being able to reproduce age-old configurations, um so people will have to navigate the options that nyx has offered during its course of history, and uh this is what essentially I'm working right now, together with uh people from summer of nix and uh domin and mike 92 from um nixon's weekend. Everyone who's really interested, for example, in phoenicial sylvan has also been joining the documentation team, while working on the next packages, architecture, effort um just to figure out strategies.

B

What's in terms of like answering questions like, what's the most impactful thing that we can do and in a limited amount of time to help people grasping the right picture of what nyx actually is.

B

And one of the questions that have been raised very quickly is well okay, so I found something out there. I want to contribute. Where would I put that- um and it turns out it's more so documentation is more than just writing things down how software works or how to use that software.

B

It's really one level higher is really. How do we communicate in the community, um because so the software that nyx is it's it's it's. We have uh the next packagement and we have this huge collection of packages and mix packages, but then we have also all these peripheral um tools, such as niv and home manager, which is not an official mix project.

B

B

Deer ant, which is kind of entangled into nyx with this next shell feature all that software is really useless if it's not accessible to those people who need it most. Those people who cannot write it on their own. So we need to communicate to these people outside of code, and if we want to help people get into that ecosystem, we have to tell them where to look for it, and so it turns out this documentation, effort kind of got into a meta crusade in well. How do we even organize our community knowledge?

B

um So what I did as a first draft in this documentation team um is just figuring out what how how do things work right now and in my impression, the discourse of the community is essentially the central hub for all the information and um a vision for what we could do in the future is start at discourse, lead people to discourse and from there help them discover all the in uh sorry when they want to contribute help them find places um to add their knowledge such that they can, it can be discovered more easily.

B

For example, if you find something, if you figured out how to deploy some service, you would just write it into the wiki and if it turns out to be a very important thing that people do most of the time, we would eventually make it end up in the manuals or the nyx.dev guide, depending on what kind of material it is, whether it's reference it should be in the manuals.

B

If it's guide, it should be in on nyx.dev, and then outsiders would just walk that graph upwards and when they discover an xos, they would first learn how to use it through the guides and then go down into the reference manuals and if those are incomplete and they will be by definition, because it's such a huge.

B

It's such a huge project, they will find additional information in the wiki and, although it should not be ideally have to still delve into the source code, and if we don't have anything there, you will always be able to resort to discourse, ask questions or find existing posts.

B

So so, really, if you want to get engaged into documentation, what you should first do is engage in the community, as most people have done so far, but my goal for the future, maybe for the next one or two years, is to go away from um the best way to learn. Nicks is to talk to people like to do sit together, and someone shows you how to do it. um Someone shows you. The relevant links is that someone can actually do it on their own by just reading the relevant material and discovering.

B

uh What is the next step to do?

B

Are we still working on this because well just gaining the overview is kind of a full-time job and then writing it down properly is still even harder, as anyone will know, who's ever written an academic paper. So the question is: uh what would that look like? um One thing that I would uh like to do is just draw more overviews like these. I mean this is already kind of a complex graph, but I came up with it in an afternoon just thinking about okay, what are those components in the next ecosystem anyway?

B

So we have the next package managers, as john told us last time. It enables hydra to build mixed packages mixed package, so nix package kind of lives on top of nix and hydra.

B

Then there's nif this external tool, which helps pinning nyx packages versions or external things and so forth and so forth, and I hope that it will, if we place these things at the right positions, and if you break them down uh well enough, not to look as complicated as this thing is, it will help people to gain a first impression of what will expect them.

B

um What I also think is that we should kind of um change the way we teach nyx in those tutorials by setting expectations more clearly, for example, while working on the next language tutorial, I just noticed. Well, yes, the next language is a simple language, but, depending on your previous knowledge, it will just take a day or two to grasp the fundamentals and then, as somebody points out learning the nyx language is not just the language itself. It's also learning the standard library, so the built-ins and also the library from nyx packages.

B

But then again you have the nyx os module system and all the particular um language ecosystems that all they have their own idioms and their own ways of doing things.

B

So, just setting these expectations up front, I hope, will help people uh well plan the effort that is required to go on that path and still we need more actual user studies where we diligently document or observe neutrally what people really struggle with and what are their actual needs, and this is something that just needs time, and I hope that people will come up and help with this.

B

So already, I've seen um a lot of contributions from the summer of nick's participants who have been um also struggling with some of the aspects of learning mix and what I would like everyone to do when they onboard into this ecosystem is to follow. Essentially the follow the boy scout rule.

B

If you see something that doesn't work out for you, write it down and write it down publicly and try to make a pull request or ask questions or add something to the wiki said that the overall state of affairs will be improved little by little and we we from the documentation team, are currently observing all these poll requests and all the issues and all the changes to nixon as wiki just to help people get their changes merged and to guide them to be effective contributors, even if they only want to spend half an hour on this.

B

But then we have more uh broad issues which cannot be done with right by contributions, and I just did a little overview um the other day to um to get an impression of what that may be. So what we're still missing, for example, is a non-technical introduction of why nyx is even relevant and how it works in non-technical terms. So we have this marketing page on on on nexus.org, but really it's um it's still fairly technical.

B

um We don't have a learning roadmap, as as I try to exemplify here like if you want to tell someone what is nix, you would have to kind of guide them through that thing, and we don't really have that. Yet um we currently have a mix architecture, a part of a documentation for the nyx architecture, as I've shown in the beginning, I'm working on a next language tutorial and then so I've outlined some of these things.

B

These are big endeavors really, so it takes multiple days to even get to a point where it's better than what we had before because writing down something in half an afternoon, that's possible and we have tens of these blog posts and uh little notes and gists, and what people do what.

B

But what we really need is a concerted effort to.

B

Polish, not just the software surface, but the path that people take when they learn about and how to use nics, and I hope that people will onboard with helping out with the little details, but I also really hope that things like the recent uh developments and the next foundation and the commercial interest that is rising in the next ecosystem will help financing the effort that is required to do that.

B

So what right now is really exceptional that I can take multiple weeks more than two months of almost full-time work on for doing this, and it seems right now, I'm mostly the only one on the planet. It seems, and I hope that we can manage to have a more um consistent work that is going into documentation and helping people learn. We have that on the development side. In some sense I mean elco is working for determinant systems. Teopan is working for tweak.

B

People are essentially doing continuous work on improving software, but what we also need, I think, is people continuously working on improving the people aspect essentially of people getting to use nics and becoming part of the ecosystem and the community and well, that's so far with documenting nics and hopefully flattening in the learning curve in in the upcoming months and years.

B

A

Thank you very much for linton that was very insightful and our colleagues over on the sidelines, solen and attila have been piling up to questions so we'll go through those. If that's okay with you.

B

A

So um first question that came in is from solana. I tried to convert a few friends to next or well: convert um not convert and like introduce weather, they replied me. uh They replied that they already had the packages in their linux distribution that they needed. So they didn't see the point of using nick's expected. It adds another layer of complexity and then what kind of argument in favor of next you use in these situations and perhaps also adds a little bit to that question. Can we document these advantages.

B

um Well, I think these advantages have been documented or told a million times already, and I don't really see the point of repeating them except for well it's a thing that you don't have to do again once it works. So that's I think my main argument for um converting to nix. But the thing is it's a trade-off. If you have a large system, you will have large migration costs. So, for example, if you have a thousand packages that you already manage in your whatever you have, converting them to nyx will take ages and it's natural.

B

um So the thing is, you will have to to figure out what's uh worthwhile for you and uh nyx does have. Of course, nyx does have migration costs.

A

Yeah the question.

B

A

Any other system in the world.

B

Just like any other system in the world, the question is: uh how long do you want to maintain this system and what next promise is essentially that you'll learn? Long-Term maintenance costs will hopefully go to zero.

A

That makes sense then atella asked. Is there a plan to create a specification for the nyx model? Ilko's thesis was written in 2003 and not many uh know what has changed since since then,.

B

Yeah, essentially, that's part of um documenting nyx architecture. What exactly the next model is, I'm not sure about the terminology here yet, um but essentially, I suppose it's the principle on how on which nix operates, and I think that should be in the next documentation itself. It's how nix works at an abstract level, where it's a different thing from the implementation. Obviously, because that's source code.

A

Makes sense and then another question from attila: um where can one follow the progress of document of the documentation team and to see where to help and what to help with this course, perhaps.

B

Yes, absolutely this course, um so we post the documentation, team meetings on the discourse, documentation, team, category or documentation category has been has been renamed recently and from there. Everything should be linked all these things that I've just shown can be accessed on the internet, and if you want, we can post them to this video, and that is what I also encourage.

B

People to do um is, if you want to, if you want to tell people things, link all the relevant resources such that people can follow them and the more essentially the more links we have the easier it should be to discover these uh information in pieces.

A

Yes, um denseland asked when blocked with a nick's syntax question. It seems most people, including myself, often find the answer on github guests. It seems the documentation lacks real world examples that are easy to understand and absorb. How do you think this could be improved in the official documentation.

B

um Good question so yeah that's a problem that are also perceived, so we have many bits of insightful information dispersed all over the place. We have parts and initials wiki. I just recently discovered a little syntax overview in the nyx packages, no actually in the nixo s manual and then the next language. Sorry, the mix manual with the nyx language section also has an entire specification, which is also kind of incomplete.

B

I think we should move all the reference style documentation into the next manual um and either have a kind of cheat sheet on the wiki or on on the manual itself and then have a collection of cookbooks or guides in one central place. There should be one place right now: it's dispersed and that's one of the efforts um that's ongoing and where anyone can easily help is just finding these instances and moving that information to a more relevant place.

B

This is the diagram that I've shown how to how information could flow in this in this ecosystem. Okay, that's something that anyone can help with.

A

Just as a librarian's job is to keep the library organized a documentary and should also organize the documents that I guess.

B

Exactly but you have to take into account that it's just such a large um system that no single person can do it and that's the whole value of the community, that we can do that together, that anyone who stumbles upon something that that's missing or broken or confusing just help out just just change that little bit. It will help enormously for all the people to come.

A

That makes sense, then solan asks it's not always clear. What next refers to is it the package manager, but also the language? What can we do with the language things.

B

uh Sorry I didn't get the last question.

A

So I believe, like what? What is it that we can achieve? What can we do with just the language itself, like nick's wow,.

B

A

Maybe also I'll extend it a little bit. um Is there something that we can help people understand the difference between nix, the language next to package manager, next packages, the package, collection, etc.

B

uh To answer the second question: first, we should be very upfront with that, as as fast as possible.

B

um Ideally in my view, we should put that on the front page of the website and really explain that distinction, uh but that's a tough nut to crack, because we have so many things depending on that front page, and um so that's still an ongoing discussion. If you follow the meeting notes, you will see that we have already talked about this, and I want this to change. I want this to improve, but right now I don't have a final answer. um The other thing: what can we do with the next language itself?

B

Well, the nix language is fairly fairly limited. It doesn't do all that much on its own and people are right and left are rightly telling. We could just replace it with anything else. It might be haskell or lisp. What name you some kind of functional or pure language.

B

The next language itself, I think, is not all that much valuable on its own. What makes it a key a cornerstone of the ecosystem is the fact that mixed packages is written in it and that's where all the value of the ecosystem lies. Essentially, this is what john was talking about last time, yep.

A

Then one more question I believe from solan is, as the next documentation is published on the next os website. Isn't it confusing for people yeah, not nixos, that aren't interested in xos, but the package manager itself.

B

Yeah, it's absolutely confusing. I want this to change. As I said, it's a hard, it's a tough nut to crack. So ideally, we would just have nicks.org as a domain, and we've talked about this, but it's really expensive to buy, and this is a foundation topic that the foundation board has to has to attack this.

A

um Then attila asks is the official documentation format still more markdown, uh since you still saw a few dog books being present.

B

uh Yes, the migration is unfortunately, not entirely complete, and this is where help is highly appreciated, so it would be. It would be a lot of help if we could just finish this. Finally, yeah okay.

A

So this is perhaps a low-hanging fruit where people can help help off.

B

Absolutely it's a fairly mechanical task, but you have to watch out a little bit so.

A

Okay and then solan asks, in addition to the documentation effort. You didn't mention the man pages for the various nix commands. Is there any plan to revamp them? I rarely find what I'm looking for in them.

B

um Honestly, I haven't been working on that yet because I think the most important uh issue that we have is, as I try to outline, is to get people to understand how to navigate the documentation in the first place, so they can learn more autonomously but yeah sure if you care about it enough, please look into it. I would be really happy to help get change, requests merged.

A

Okay, um I also had a question of myself and that plays into the the low hanging fruit that I just mentioned. That attila said, like the mark done versus dog book thingy, um do you think there's other low-hanging fruit that people can very easily jump on to without too much fear of being judged? I guess.

B

Yeah, there's a bunch uh so in that little graph that I've shown uh how to add information and insights into them into the relevant documents. It's a whole post that I wrote for the summer of nix participants, but which really applies to anyone who wants to contribute to next.

A

B

A bunch of long-standing issues that we can uh easily approach with without much commitment, so one of them is helping categorize the mixers wiki. So we have like 50 to 100 orphan pages, which don't have a category which are essentially not findable. Unless you know the terms to google for there's a few things that you can always do is.

B

Figuring out what kind of information is missing from next packages? So I've told this multiple times now. So if you stumble into something that doesn't work for you and it doesn't say anything about it in the manuals and there's no information in the wiki, just add it to the wiki.

B

If you see something in the vp that is really polished and it just works, it should be in the manual probably so if it's kind of this is how it's done- and um this is the interface that exists put it into the manual, for example, um we have still haven't detected because there's so much to do, there's always much more work than we have time. um There's no proper explanation of what nixos modules are in the nixos manual. It's in the mix as wiki just move that article into the mixer s manual.

B

That will be something that anyone could do at any point in time. Yeah.

A

That would make very much sense, actually um perhaps more of a personal question. um I have had to write documentation in the past as well, and I always got a little bit scared of publishing the documentation. If that makes sense, because I was afraid of it not being well worth in the north or if there were too much spelling mistakes or just language or grammar mistakes. um Is this something you think people should fear or is it just publish it? And people will it'll evolve over time.

B

Yeah, I think language and grammar are really the least things to worry about, although there's like two aspects to it, if you make a pro request and it's barely um understandable, barely legible, that will probably not entice people to review it, so it should be at some some um mainly readable level, but you can always use online tools like language tool to fix that, for you um or just ask someone to to review it first, ask your friends: do you understand it, um but other than that small mistakes will always helpfully be.

B

um There will always be people helpful in uh fixing those, and also what I also observed a lot of times is that if people actually introduce their misconceptions into their pull requests, there's usually someone who will say wait a minute. This is not how it works. It's actually that way, and then these things will evolve.

B

Naturally- and the other thing is yes, please just add your contributions as you see fit, um for example, it should be super easy to contribute to the nexus if you just find something and don't be afraid of it being incomplete or not well worded. What you can always do to make sure is just ask someone who doesn't know and observe them interacting with that thing.

B

It does take time, but that will make sure that you've struck the right angle and um that that thing even makes sense. If people are still confused, then probably you should rework it.

A

That makes sense, um and then we had a little talk before the lecture actually started, and you had mentioned a book that you didn't mention during your talk that the.

B

Yeah right source.

A

Of inspiration.

B

uh Absolutely a colleague recommended me the following book, which I always have on my table right now.

B

It's called how learning works, and this is what I'm mostly basing my documentation work on, because it um it's something like a meta survey of the past hundred years of learning science and very concisely and aptly explains how people construct their internal knowledge graph, as I would call it and I highly recommend reading it. If you want to try helping people acquire some skill or knowledge, because it's I mean it's super helpfully written. I wish I could write as um focusedly and concisely as they do in this book.

B

Like it's, I would say for this line of work. It was like life-changing to me.

A

Nice, I do not think there is any more questions. I myself also do not have any questions left.

A

So I'd like to thank you valentin, for these amazing talk and insights on the nexus x, documentation and trying to flatten the learning curve of nyx, um and then I'd also like to thank our colleagues and the sidelines as solan and atila for just pumping in the questions and making them come in. So yes, thank you again. Valentin yeah.

B

Thank you for having me, I.

A

Wish you the best luck with the documentation.

B

A

If only my mic was immuted, you would have actually heard what I said.

B

A

Terribly sorry for that, so yeah, what I said is, since valentine isn't her life. Currently he will answer questions eventually in the matrix channel. You can check that over below here, he'll either answer somewhere this evening, or perhaps tomorrow, most probably tomorrow, but he'll. He study to try and answer them.

A

I'd also still like to thank the people that made the summer of nick's happen. Special thanks to, of course, the anal net foundation, the european commission, the nexus foundation and tweak for their support in making all of these things come together and actually getting them out there.

A

I hope you guys enjoyed this lecture next week same time, we'll have a new lecture with domin. We do not have a title for that yet, but keep an eye out on this course. For that one. Thank you all for watching, and I wish you all a great night.