 | Nix Documentation | 404 Members |
| Discussion about documentation improvements around the Nix ecosystem | 80 Servers |
| Nix Documentation | 404 Members |
| Discussion about documentation improvements around the Nix ecosystem | 80 Servers |
| Sender | Message | Time |
|---|---|---|
| 6 Feb 2024 | ||
 @fractivore:cyberia.club |  Download mermaid-diagram-2024-02-05-222724.png | 04:28:24 |
 danielsidhion | In reply to @fractivore:cyberia.clubYou need to define more styles if you want to ensure all colors will match on all cases. On the live editor if you switch to the dark theme (the default that my browser uses) you'll see the text color doesn't work well with some of the backgrounds. Regarding the technical bits: there is no "exit subroutine" that sets things back. nix-shell is an entirely new shell on top of whatever shell you ran nix-shell ... on, so exiting is really just ending the nix-shell process, and then you'll be back on your original shell.More generally: I think adding diagrams to tutorials won't be productive, because a tutorial is meant to be more like a "step by step" thing rather than "what is happening" thing. There are definitely exceptions though, especially with more complex topics. I did a very quick look at the pages in the "tutorials" section on nix.dev again, and I think the pages that aren't on the "first steps" subsection are good targets for some diagrams. | 11:22:25 |
| danielsidhion | Also on the technical bits: the "nix-shell entry subroutine" box should ideally be inside the "nix-shell" box | 11:24:04 |
 infinisil | symys I tend to agree with danielsidhion that nix-shell isn't that good of a fit. It could work a bit better if the boxes represent forked processes, though that would be a very simple diagram. | 11:39:48 |
| infinisil | symys Looking through nix.dev myself, I can see potential for the [cross compilation](https://nix.dev/tutorials/cross-compilation) page to have a diagram for the difference between the platforms | 11:41:05 |
| infinisil | Could even include how Nix evaluation and remote building ties into that | 11:43:30 |
| infinisil | It's not done yet, but the [thunks tutorial](https://github.com/NixOS/nix.dev/pull/824) could really use diagrams. Haskell has an entire package for visualising thunks in practise even: https://dennis.felsing.org/ghc-vis/ | 11:50:22 |
| @fractivore:cyberia.club | Thanks for the feedback! | 12:44:28 |
| @fractivore:cyberia.club | In reply to @infinisil:matrix.orgI think its okay if a diagram is really simple, "obvious" even as long as it's accurate and the reader knows it. | 13:06:57 |
 @qyriad:matrix.org | I tend to agree, but there is a limit to how simple is still worth showing | 13:08:05 |
| @fractivore:cyberia.club | Folks can probably guess it due to the way this convos started but I am a huge fan of diagrams and graphs 😁 | 13:08:05 |
 Dominic Mills | Greetings everyone, Season of Docs opened up their applications on the 2nd of February. I wanted to check with you guys if you're fine with me coordinating this activity for the NixOS Foundation? I have previously successfully managed a prior Season of Docs participant in 2022 (see 'Talawa' in https://developers.google.com/season-of-docs/docs/2022/participants). If everyone agrees, I can draft a CFP in the following days that details the strategies we could use for this edition of the programme. | 13:11:15 |
| danielsidhion | I think simple diagrams are fine as long as they belong in a page intended to explain things and improve content overall | 13:12:22 |
| @fractivore:cyberia.club | In reply to @dmills27:matrix.orgErm, whatever it's worth, I am 100% fine with that 😆 ( the emoji is because I'm a noob, and while my opinion is still valid, there is truly very little weight to my opinion in this situation ) | 13:22:50 |
| @fractivore:cyberia.club | In reply to @danielsidhion:nixos.devHuge thanks. Would you be willing to elaborate more on the details of nix-shell as a process, and/or know where I can read more about it? I've had a tough time finding the source code! It's not really discoverable in the same way nixpkgs source is (it's not in nixpkgs....? right?) , and it's also not a very easy thing to search for, due to the huge amount of ambiguity (nix shell vs nix-shell vs Now open up a shell and install nix...). | 13:40:05 |
| @fractivore:cyberia.club | I read the manual, but it's a manual - intended for usage rather than understanding. | 13:41:11 |
| @qyriad:matrix.org | It's not in Nixpkgs, confusingly it's in NixOS/nix/src/nix-build/nix-build.cc https://github.com/NixOS/nix/blob/master/src/nix-build/nix-build.cc | 13:43:17 |
| @fractivore:cyberia.club | In reply to @infinisil:matrix.orgThis is a completely new concept to me (thunks) , so I'll need to do some reading first, but thanks for the direction. | 15:01:35 |
| danielsidhion | In reply to @fractivore:cyberia.clubAside from the source code already provided, I don't have any specific resources to link to. The concept of a shell and processes are more generic and not particular to nix, so to learn more about those, you'll have to learn a bit about operating systems. nix-shell is mostly just a regular shell with some extra stuff on top as you detailed in your diagram | 15:49:09 |
 fricklerhandwerk | In reply to @qyriad:matrix.orgsymys: Not only is it confusing - the flagship feature we put on the front page is a really ugly wart architecturally. Maybe the ugliest. We’re still discussing how to maneuver away from it and still provide the same or better level of convenience and maintainability, but it requires pulling on multiple ends of the problem to get done. I recommend not to sweat it and focus on more pressing issues, namely those large areas that are not properly documented at all. | 16:24:16 |
| fricklerhandwerk | Which is to say: nix-shell is well-understood at the surface and has enough reference documentation to get quite far. The sharp edges and thorny problems are somewhere else. | 16:26:57 |
| @fractivore:cyberia.club | Maybe, but also keep in mind that I came to this diagram through an organic process of reading through the doc as a learner and reflecting on what wasn't quite clear to me. | 16:35:58 |
| @fractivore:cyberia.club | Looking over everything I could find on my own about nix-shell, in fact | 16:36:30 |
| @fractivore:cyberia.club | Of course, everybody follows a unique learning process and gets hung up on different details, owing to their diverse backgrounds. | 16:39:49 |
| @fractivore:cyberia.club | But yeah my motivation here isn't just entirely selflessly wanting to document stuff for the community. I mean I do want to give back to the community, but I also need to spend a lot more time reading existing docs to get a better understanding of Nix and NixOS myself. I thought an efficient way of deepening my own understanding while also contributing would be to go through all of the existing materials and make diagrams of stuff that jumped out of me. Then I can present the diagrams, where they can be accepted and/or modified or rejected. That being said I'm also very happy to take feedback on stuff that is under-documented or lends itself well to diagrams or whatever, I mean I like to be useful | 16:48:32 |
| fricklerhandwerk | In reply to @fractivore:cyberia.clubYes, writing down (or graphing) what you understand and bouncing that against people is a great way to learn! | 16:50:22 |
| fricklerhandwerk | In reply to @dmills27:matrix.org Hey, it would be great if you kicked of the process with a CFP, because we should definitely take the opportunity to get funding. How far do you want to go with it? Are you willing and available to drive it to conclusion: progress tracking, evaluation, final report, the whole project management long tail? | 16:56:34 |
| fricklerhandwerk | In reply to @dmills27:matrix.org* Hey, it would be great if you kicked off the process with a CFP, because we should definitely take the opportunity to get funding. How far do you want to go with it? Are you willing and available to drive it to conclusion: progress tracking, evaluation, final report, the whole project management long tail? | 17:07:55 |
| fricklerhandwerk | * Dominic Mills: Hey, it would be great if you kicked off the process with a CFP, because we should definitely take the opportunity to get funding. How far do you want to go with it? Are you willing and available to drive it to conclusion: progress tracking, evaluation, final report, the whole project management long tail? (bearbeitet) | 17:09:59 |
 megs78 joined the room. | 19:13:44 | |