| 31 Jan 2024 |
|  @federicodschonborn:matrix.org changed their profile picture. | 06:22:01 |
|  Ryan Yin joined the room. | 09:14:07 |
| 1 Feb 2024 |
|  deightz joined the room. | 04:05:19 |
 henrik-ch | I won't make the meeting today - sorry and have a good session! | 14:26:40 |
| 3 Feb 2024 |
|  raboof changed their display name from raboof to raboof @FOSDEM. | 07:38:48 |
| 4 Feb 2024 |
|  Bryan Honof changed their profile picture. | 11:31:25 |
| raboof changed their display name from raboof @FOSDEM to raboof. | 17:41:37 |
 @fractivore:cyberia.club | I would like to help with documentation. I have put some time into learning Nix and NixOS but would still consider myself a beginner-level learner. Helping with documentation is a recommended starting contribution, and also seems like an efficient way to take excellent notes as I go that can also benefit others.
But also, I really like diagramming things, and I've noticed there is a shortage of visual documentation components. I am looking for some guidance on what might be some good things to diagram that people have noticed or thought of. I'm thinking:
- Organizational graphs (maybe something about store layout)
- Mnemonic devices ( Venn-diagrams pertaining to use-cases of flakes vs modules, or something like that )
- Really, my goal is abundant and diverse visual learning aids. Doesn't have to stop at visual media even.
| 18:01:41 |
| @fractivore:cyberia.club | I was thinking about starting with some of the diagrams in https://edolstra.github.io/pubs/phd-thesis.pdf , like taking them as a starting point, determining if anything has changed since the thesis was released, then building diagrams (as code, preferably) with a little more color or whatever. Then going from there. | 18:04:01 |
| @fractivore:cyberia.club | Has anybody ever looked at a doc and said "I wish there were less diagrams"? 🤔 | 18:04:42 |
 @qyriad:matrix.org | Yes, but only when they were bad =P Go for it, the docs could definitely use some visual aids | 18:05:37 |
 danielsidhion | Diagrams are welcome! Feel free to ask if you need help reviewing them or with anything else | 18:23:05 |
| @fractivore:cyberia.club | One thing I'm wondering - if I want to do diagrams as code, are the docs opinionated as to what language I'd do that in? I've used that python diagrams as code library a lot. But also webGL... Could do Go or something..... | 20:15:07 |
| @fractivore:cyberia.club | WebGL is awful heavy, idk if rendering to html canvases would be good at all... Python diagrams would actually make maintaining the diagrams pretty easy but I don't know how well it would integrate with the docs. | 20:17:52 |
| @fractivore:cyberia.club | nix.dev seems to have a lot of python stuff, so the https://diagrams.mingrammer.com/ thing should actually be kinda perfect right? | 20:45:54 |
| @fractivore:cyberia.club | Oh I got an idea for my first diagram here: "Map of the Nix Documentation Multiverse" | 21:01:55 |
 infinisil | symys: That sounds great! I'd be in favor of Mermaid diagrams, because GitHub supports them natively now | 22:36:16 |
| infinisil | And I'd expect sphinx (which is used for nix.dev) to have a plugin for that too | 22:36:43 |
| 5 Feb 2024 |
 Austin Horstman | Been using mermaid diagrams at a client and have really liked ‘em so far. | 00:31:34 |
| infinisil | I also added one to the contributor docs :D https://github.com/NixOS/nixpkgs/blob/86a5d2482eecde9579c2f073e04a14e170ef5e31/CONTRIBUTING.md#staging | 00:43:23 |
| @fractivore:cyberia.club | In reply to @infinisil:matrix.org
I also added one to the contributor docs :D https://github.com/NixOS/nixpkgs/blob/86a5d2482eecde9579c2f073e04a14e170ef5e31/CONTRIBUTING.md#staging Nice, now I can look at how you did that 😄 I was thinking those commit graphs looked like something that might come in handy! And it just adds some color into the doc right away which is nice! | 12:08:52 |
 Sandro 🐧 | Someone can have a loom at https://github.com/NixOS/nixpkgs/pull/252091 ? | 18:11:31 |
|  @ThorHop:matrix.org removed their profile picture. | 22:45:09 |
| @ThorHop:matrix.org removed their display name IdeallyYes. | 22:46:17 |
| @ThorHop:matrix.org left the room. | 22:46:55 |
| 6 Feb 2024 |
| @fractivore:cyberia.club | So I decided to just start going through nix.dev in order and see if anything jumped out at me as worth diagramming. The nix-shell environment occurred to me when nix-shell came up early on. So, I attempted to diagram a little more detail of "what is happening". I was wondering if somebody could check my diagram for accuracy, and suggest improvements as to its accuracy. You can view the diagram in the mermaid live-editor here: https://mermaid.live/edit#pako:eNqtll9r2zAQwL_Kzd2jzdK9DPww2JZCH7YySBgMDJssnRpRWTKSHCd0_e6TZSe2Ezul3QiYWNb97v9JjxHVDKM0ypR1xOFSkHtDimT7PlNMGKROaAXrz5nKFKF0LZzEFO7ELrEblBIo8Q_ckaKUCHZvHRaJxC1KYC0piC3RUpPCShcIDB0REjQHAurIkUiMEur-wIqBWL8h2NSjmh8AUEmsXSLvFK4CgQsp06vFgl_HXCuX1CjuNy7NtWSxdUY_YFIL5jbpdbnrFtJcEvpwgqxyoysnFLZEuGKcLzi-hOHd-q82OTSFUKTjhQ0x1VKb9Ip9wAXnL6b3_KOxN2orjFYFKndcm9zmzH51DFLcf9gJ168P4jiAdAn72hTImdJBMgcipcFWZVMJ8aE87jqlX3RREMVioNrWZH98LbV1waBQP4f4dX6PmZAkHy_Z1YpM6w2yM5Fp5WY-ngieKJtKyUhgFOpW5lJkG9lRRA6BaNsri1ZBGLqW7nwrjS5KB6QmwoXObFzIoqYxRwH8R9TYrnNUN07auggil1x9PLg2BP3UFZhKpfC7HzhJ2dUMSC0pcb9b9kyee-Y5vWcGt4aV740J1Lkq6GFDIMMSFUNFBdpmTnZ2Nna0tkJeCekuoqfJOIjUlhhBculVWHwN6-1qvby5-_Hr-6f17TuPqEqwujIU2StgIX63Wj-EAwV9Bwv-Arumkn5MyyljVCxDY8Zvo4nybPtNM84LkOra-lzeeoyOm3P0DfwZV-BI73M49KZMy01LDmrVSw5LdRyk8SyfyRk68D1o9m7T9HTuDxZwGja6Bo-uPS5Hrg02poajfS4jJ-GcC2j_76n92z6fojgq_IAngvlrTEhpFrkNFt6nNHQTJ1XTLZlqtpLK6dVe0Sh1psI4qkrWX3uilBNp_Soy4bT51l6Nwg3p6S-2Tiw- | 03:01:02 |
| @fractivore:cyberia.club | The diagram is supposed to go with: https://nix.dev/tutorials/first-steps/ad-hoc-shell-environments | 03:01:35 |
| @fractivore:cyberia.club | 
Download mermaid-diagram-2024-02-05-222724.png | 04:28:24 |
| danielsidhion | In reply to @fractivore:cyberia.club
So I decided to just start going through nix.dev in order and see if anything jumped out at me as worth diagramming. The nix-shell environment occurred to me when nix-shell came up early on. So, I attempted to diagram a little more detail of "what is happening". I was wondering if somebody could check my diagram for accuracy, and suggest improvements as to its accuracy. You can view the diagram in the mermaid live-editor here: https://mermaid.live/edit#pako:eNqtll9r2zAQwL_Kzd2jzdK9DPww2JZCH7YySBgMDJssnRpRWTKSHCd0_e6TZSe2Ezul3QiYWNb97v9JjxHVDKM0ypR1xOFSkHtDimT7PlNMGKROaAXrz5nKFKF0LZzEFO7ELrEblBIo8Q_ckaKUCHZvHRaJxC1KYC0piC3RUpPCShcIDB0REjQHAurIkUiMEur-wIqBWL8h2NSjmh8AUEmsXSLvFK4CgQsp06vFgl_HXCuX1CjuNy7NtWSxdUY_YFIL5jbpdbnrFtJcEvpwgqxyoysnFLZEuGKcLzi-hOHd-q82OTSFUKTjhQ0x1VKb9Ip9wAXnL6b3_KOxN2orjFYFKndcm9zmzH51DFLcf9gJ168P4jiAdAn72hTImdJBMgcipcFWZVMJ8aE87jqlX3RREMVioNrWZH98LbV1waBQP4f4dX6PmZAkHy_Z1YpM6w2yM5Fp5WY-ngieKJtKyUhgFOpW5lJkG9lRRA6BaNsri1ZBGLqW7nwrjS5KB6QmwoXObFzIoqYxRwH8R9TYrnNUN07auggil1x9PLg2BP3UFZhKpfC7HzhJ2dUMSC0pcb9b9kyee-Y5vWcGt4aV740J1Lkq6GFDIMMSFUNFBdpmTnZ2Nna0tkJeCekuoqfJOIjUlhhBculVWHwN6-1qvby5-_Hr-6f17TuPqEqwujIU2StgIX63Wj-EAwV9Bwv-Arumkn5MyyljVCxDY8Zvo4nybPtNM84LkOra-lzeeoyOm3P0DfwZV-BI73M49KZMy01LDmrVSw5LdRyk8SyfyRk68D1o9m7T9HTuDxZwGja6Bo-uPS5Hrg02poajfS4jJ-GcC2j_76n92z6fojgq_IAngvlrTEhpFrkNFt6nNHQTJ1XTLZlqtpLK6dVe0Sh1psI4qkrWX3uilBNp_Soy4bT51l6Nwg3p6S-2Tiw- You 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 |
