2023-05-11 - Learning Journey Working Group - Meeting Notes #8

zmitchell · May 12, 2023, 8:28pm

2023-05-11 - Learning Journey Working Group - Meeting Notes #8

Previous meeting notes
Attendees: @zmitchell @khaled @henrik-ch @infinisil @Jeremiah
Notes taken by: @henrik-ch

Review of what we decided for the tutorial series last time

Python web server
Postgres database
set up Python dependencies in nixpkgs
set up NixOS tests
integration tests using Nix-only facilities

Identifying first steps of the journey

@zmitchell - First step: nix-shell -p tutorial
- this can be our first iteration of the webapp
- single python file with a hello world app using Python standard library
@zmitchell - Second step: shell.nix with no new dependencies
- Verify that the webserver runs using the Python defined in shell.nix
@Jeremiah sounds like a good starting point - shall we introduce conscious errors?
- @zmitchell - might be a cognitive overload on the beginner user

When to teach the Nix language

@zmitchell - is this the point where we teach nix language and pinning?
- @infinisil - mention that the nix language is used - and direct them to tutorial if interested - but not making it a requirement to move further.
- @zmitchell - @fricklerhandwerk added a flowchart for sequencing, see below
@infinisil - introduce shell.nix, introduce language incrementally, and it’s also not a problem to say nix language is a requirement to continue.
- @khaled - we teach enough nix language as we go, right? we don’t want to stop the whole tutorial to deep dive in the language tutorial?
- @infinisil - function calls, lists, attribute set declarations, lambdas? - the list gets extensive quite quickly.
@Jeremiah - could it be alongside? not breaking it down - but more linking it from the shell.nix file?
- @infinisil - (see example below) - can we link to nix.dev and reference manual in comments?
- @infinisil - on nix.dev - we can add a more direct reference to the reference manual
- @zmitchell & @khaled - we might have a formatting problem - how to make clickable links on our language snippet
- @zmitchell first shell.nix should be as minimal as possible - difficult to distinguish import syntax parts - noisy
@zmitchell - alternative - give the user a shell.nix with python - you don’t need to understand it yet. Then in the next tutorial use this shell.nix as an example for explaining the Nix language.
- @Jeremiah - this may be helpful
- @Jeremiah - beginners look at the language - and they can’t see the correlations - what is a function inside a shell et cetera.

Contents of shell.nix tutorial

@zmitchell - introducing the Nix language after shell.nix tutorial means shell.nix tutorial is left with little content
- @zmitchell - can we enrich it without introducing additional concepts?
@infinisil - can we introduce the pinning? it helps for reproducibility - but demands pinning skills
- @zmitchell - pinning is a later step
- @infinisil suggesting first depending on the NIX_PATH, and then move to a pinned example
- @Jeremiah this means we start out in a non-gradual way? you show the granularity that nix can provide in steps, rather than starting with the full details.
- @infinisil start using nixpkgs with shell.nix - next is github branch - you can fetch expressions using nix
- @zmitchell - thinking channels inside pinning parts - like an intermediate step?
- @infinisil - different levels of nix purity - evaluation, runtime & more
- @zmitchell - when we do pinning do we add the nixpkgs aspect?
@zmitchell - idea about the env variable in the example
- Set an environment variable in shell.nix
- Use the environment variable in the Python web server
- Now the user sees how to configure the behavior of their server declaratively with Nix
@infinisil - nix tutorial is not a prerequisite (yet)
- @infinisil - if people feel confused, it makes them motivated to read the nix lang tutorial to keep up
- @Jeremiah - shell.nix tutorial - because it hasn’t been in depth explained - as a new user they are motivated to continue
@infinisil - you can put the shell hook stuff in the --run on the nix-shell -p command
- @infinisil you can add exports to the shell hook
@zmitchell we add environment variable from the start - maybe we leave it out from the nix-shell -p initial example
@zmitchell - let’s recap the steps we’ve figured out
- nix-shell -p - small server standard python
- shell.nix tutorial - minimal env customization
- nix language - explain the shell.nix we made
- Evaluation purity
  - non pinned fetching, link to something channels (how published - pushed to branches etc.)
  - introduce pinning - pinned fetching, mention prefetchers, niv and flakes - just as links/pointers
  - system, config, overlays

Adding Python dependencies

@zmitchell - reader needs to find flask
@infinsil - now we need a builder from nixpkgs.
@zmitchell incremental approach - add flask to shell and get it running
- flask has a CLI for running the app, no issues with PYTHONPATH
@zmitchell the derivation may complicate things
@infinisil flask is under python packages
@infinisil: How about pkgs.python3Packages.buildPythonApplication, but not building it yet, just using it as a shell instead of mkShell.
@zmitchell - if we abandon pkgs.mkshell fo buildPythonApplication we need to justify why we make the switch
@zmitchell - we could add a library, not a binary, to demonstrate the value of the python builder vs the mkshell.
@Jeremiah - or a postgres integration
@infinisil - a stepwise approach, buidling the python package as passing it along into the shell environment
@Jeremiah - we are looking for an iterative process
@khaled - start with a simpler default.nix
@infinisil - Move towards this pattern for building

mkShell {
    buildInputs = [
        python3Packages.flask
    ]
}
=>
let
  myPackage = python3Packages.buildPythonApplication {
    propagatedBuildInputs = [
      python3Packages.flask
    ];
  };
in myPackage // {
  shell = mkShell {
    inputsFrom = [
      myPackage
    ];
    buildInputs = [
      curl
    ];
  };
}

# shell.nix
(import ./default.nix).shell

@zmitchell - how to explain what Nixpkgs is?
- @infinisil - Packages, package search
- @infinisil - The library, non-derivation creating
- @infinisil - Derivation-creating functions, fetchers, builders
- @henrik-ch: Do you need the structure for pinning?
  - @zmitchell: Not for using but if you wanna look at expressions
  - @infinisil: pkgs.hello.meta.position, nix edit -f '<nixpkgs>' hello
  - Package search contains a link to the source
@infinisil: Package search would be useful even before nix-shell -p
@Jeremiah: Refer to the search afterwards when needing new packages for repetition
Let’s stick with online package search, no CLI because it sucks currently
- @infinisil: Also later the nix repl is introduced, auto-completion

Example of an annotated Nix file (let’s not do this)

# shell.nix
{        # Function argument declaration (link to https://nix.dev/tutorials/first-steps/nix-language#functions)
  pkgs ? # Function default ...
    import
      (fetchTarball "https://github.com/NixOS/nixpkgs/archive/06278c77b5d162e62df170fec307e83f1812d94b.tar.gz")
      {},
}:

pkgs.mkShell {
  buildInputs = [
    pkgs.which
    pkgs.htop
    pkgs.zlib
  ];
}

Knowledge graph

flowchart
  lang[Nix language] --> shell[shell.nix] & drv[declaring derivations]
  drv --> python[Python packaging]
  pinning[pinning Nixpkgs]
  lang --> modules[module system]
  modules --> config[declarative configurations]
  shell & config --> devenv[development environments]
  config & testing[NixOS testing framework] --> vmTests[NixOS VM tests]
  pinning & lang --> reproducible[reproducible builds]

alper · May 13, 2023, 1:51pm

Can you list the learning goals that somebody following this would achieve?

fricklerhandwerk · May 13, 2023, 4:40pm

I agree with @alper here. Judging from this and prior discussions, which are kind of circling around the same set issues without conclusion, we may want to focus on pulling apart the concepts and skills involved in even the simplest setup. Then reassemble that into a reasonable sequence.

Generally for tutorials, assuming we have fully specified prerequisite knowledge, each step should be obvious in terms of what it does, even if we don’t provide direct explanation on why we do it. Dumping a full 50LOC example on learners will not fly.

zmitchell · May 13, 2023, 7:50pm

Can you list the learning goals that somebody following this would achieve?

Sure, no problem:

nix-shell -p python310
- You can create an ephemeral shell environment that has certain packages in it that will no longer be in your environment when you leave the shell. This is useful for experimentation.
shell.nix
- Note: We give a short shell.nix scaffold here and point the reader at literally two lines: including Python and setting an environment variable. We also tell the reader that the language will be explained in the next tutorial (not a nebulous “later”, literally the next tutorial).
- Once you’ve experimented with packages in an ephemeral shell environment you can “save” and declaratively configure that shell environment.
- You have avenues to declaratively configure other aspects of that environment, such as code to execute before entering the environment (shell hooks), setting environment variables, etc.
Nix language
- Understand the basics of the Nix language such that you can understand the details of the shell.nix used in the previous tutorial.
- Note: we intentionally introduce shell.nix before the language tutorial so that the reader isn’t just learning the Nix language for the language’s sake, they’re learning it via a specific application of the language.
Pinning nixpkgs
- Your package dependencies have to come from somewhere, and that somewhere is nixpkgs.
- In order for your build to be truly reproducible you have to pin your shell/derivation to a specific revision of nixpkgs.
- Whether you want your build to be truly reproducible is up to you, and if you don’t want or need it to be so then you have options for how to specify where your packages come from.
Including Python dependencies
- Self explanatory, how to include Python dependencies through nixpkgs rather than pip, poetry, etc.

That’s what we have right now, there are several more steps and subsequent meetings will fill out steps that come after what I’ve listed here. We’ve spent the last few meetings building out that knowledge graph and choosing the specifics of the project to meet a few goals:

Not be too difficult
Take the reader through a likely use case
Cover a wide variety of topics

Judging from this and prior discussions, which are kind of circling around the same set issues without conclusion,

I disagree with this characterization pretty strongly. Like I said, we spent a few meetings considering a range of possible projects the reader could walk through, discovering the difficulties that you run into in each case, and finally landing on the current project. In that sense we have a conclusion so I don’t know where “without conclusion” is coming from.

we may want to focus on pulling apart the concepts and skills involved in even the simplest setup

That’s what we’ve been doing until now. The other consideration is that I’d like the learner to be building towards something, not doing isolated tasks. That’s why it took us a while to settle on a project, there’s a lot of design constraints and finding a project that’s useful and threads the needle of learning small enough concepts in the right order is not easy.

Dumping a full 50LOC example on learners will not fly.

Not sure what you’re referring to here, the only things we’re “dumping” on the learners would be

a short Python script, which is not what we’re trying to teach so I feel justified saying “just trust us that this makes a server”
a shell.nix that looks like this:

# Don't worry if this looks alien, we'll explain it in the next tutorial!
{ pkgs ? import <nixpkgs> {} }:
pkgs.mkShell {
  buildInputs = [
    pkgs.python310  # Add a package here
  ];
}

This is 6 lines, not 50, and we immediately explain it in the next tutorial. It sounds like there’s concern about cognitive overhead presenting new topics to the learner, and I hear that and wholeheartedly agree, but 6 lines feels manageable.

Happy to answer other questions or address concerns about the approach. I think we’ve chosen a path that has merit, but if there are other approaches that would better serve learners that also meet the design constraints I’m happy to hear those ideas.

alper · May 13, 2023, 8:54pm

OK. Here’s my assessment as somebody who’s just been through the worst of it.

For me this is more a party trick than anything, but it’s still neat.

I’d push this all the way to the back. I don’t think any knowledge of the language is necessary to be able to add packages to your shell.

A line by line explanation of the shell.nix probably will suffice at the moment. Also it’d be cool if people would just be able to type and not overuse things like with and inherit. A nix file would be I think much easier to understand for a beginner with everything written out.

Yeah, that’s great.

I’d pull this up. This is an immediate follow-up to the shell thing.

Then you’d need to add a thing to package the Python up or get it ready to run for production and you’re done. That’s a full trip start to finish.

I’d push the language tutorial all the way to the back. What’s been most problematic for me has not been the language, but everything that’s implicit and in stdenv:

“This part is bash for some reason? This means all this stuff will be copied to store? installPhase is hard required? This is $out and this is ${out}?”

I think the biggest win will be if this thing has rock solid real-life example files that people can drop in and tweak.

I’d drop this entirely. Nobody who’s beginning this needs this. If they need it, they’ll probably be able to figure out how to get it.

zmitchell · May 14, 2023, 2:14am

For me this is more a party trick than anything, but it’s still neat.

I hear where you’re coming from, but I disagree and here’s why. I think a useful approach is to take baby steps, and the first concept we’re teaching is that with Nix you can construct these ephemeral shell environments that can be isolated from your global system configuration. If we’re going to teach that as the first concept, which is useful because you can build on it to then teach how to build development environments, which certainly isn’t a party trick, you have two options:

Teach nix-shell -p as a means of creating an ad-hoc environment
Teach shell.nix so that you can call nix-shell

In this context nix-shell -p is clearly the lighter lift for the reader. Not only that, but it gives us an avenue to teach some other benefits:

If you have a program installed as part of your OS, you can use a newer (or older) version in an isolated environment without worrying about modifying system files (looking at you, system Python).
You can use nix-shell -p to use a program once without needing to globally install its entire dependency tree.

The second bullet point could be seen as a party trick, but anecdotally I’ve used it several times for this exact purpose.

I’d push this all the way to the back. I don’t think any knowledge of the language is necessary to be able to add packages to your shell.

A line by line explanation of the shell.nix probably will suffice at the moment.

“All the way at the back” of the tutorial series would be after teaching how to use NixOS VM tests as a means of running integration tests. I’m not sure if you’re aware of that or if you just mean put it at the back of the tutorials that are listed in the meeting notes above. In either case:

If you mean literally all the way at the back, I don’t agree with that at all because you’ll need the Nix language for writing derivations, setting up tests, etc.
If you mean at the end of the tutorials listed above, I still don’t agree because in my opinion explaining shell.nix line by line would just be a less thorough version of teaching the Nix language. There’s a lot of features you could explain just going line by line. Being able to say “this is what a Nix function looks like in general: ____” and then immediately connect it to a concrete example (e.g. “you can actually see that our entire shell.nix is a function with ____ as the argument and ____ as the body”) is very useful.

I’d pull this up. This is an immediate follow-up to the shell thing.

Then you’d need to add a thing to package the Python up or get it ready to run for production and you’re done. That’s a full trip start to finish.

There’s definitely merit to having an MVP running early on and only then adding features. However, I really think there are just too many new concepts to introduce between nix-shell -p and buildPythonApplication to make this something we do early on. Like I said before, I want to take baby steps.

What’s been most problematic for me has not been the language, but everything that’s implicit and in stdenv

For sure, I totally get that, and I suspect that’s a very common stumbling block. I’d be very interested in hearing specifics about which stumbling blocks you ran into and if you have suggestions for how to put them in the reader’s path at some point without arbitrarily having them run into an error for the sake of running into an error.

I think the biggest win will be if this thing has rock solid real-life example files that people can drop in and tweak.

I would love for those materials to exist, but that’s not a tutorial, that’s a how-to (what we’re calling a “recipe” to make the distinction clearer)! See here for more information on the distinction.

I’d drop this entirely. Nobody who’s beginning this needs this. If they need it, they’ll probably be able to figure out how to get it.

Again, I hear what you’re saying, but I disagree. If all you want is a thing that builds, sure, you don’t need to pin nixpkgs. However, for the purpose of teaching the ins-and-outs of Nix, I think it’s important to teach this.

For example, we may tell a reader that if all the dependencies are already built, the only piece that will get rebuilt when they run nix-build is their source. If they haven’t pinned nixpkgs they may be surprised when they go run nix-build and discover that it’s downloading a bunch of packages. Didn’t we just tell them that they wouldn’t need to rebuild anything? Why is Nix doing all this extra stuff?

Furthermore, if you’re trying to show a reader that they can have the same environment in development and production you should be able to verify that the store paths are the same on the local and remote machines (as long as system is the same, etc). If you haven’t pinned nixpkgs that’s unlikely to be the case.

By the way, I just want to say I appreciate your questions. I want to make it clear that a lot of thought has gone into what we’re doing and that there’s a rationale. I also want to make sure that we make good use of all of the volunteered hours that are going into this. I would be sincerely crushed if we put a ton of time into this and it turns out to be a dud that doesn’t move the needle. Getting feedback and having people question our methods is a useful part of the process.

alper · May 14, 2023, 7:52am

OK. Then go at it and don’t take any feedback from somebody who’s reasonably qualified.

I think the outline posted above is pretty much the same as this?

https://nix.dev/tutorials/first-steps/

I followed that and it wasn’t very helpful (though better than nothing) and rather awkwardly put together and sequenced.

Is the intention to improve on that or is this something separate?

More radically (which nobody here will listen to but I think it’s more correct than inundating new people with technojargon), I think there should be a separation between Nix-packagers and Nix-users. It would be good if Nix-users could get a serious amount of stuff done without knowing many details about nixpkgs or nixlang. Similar to how with homebrew you can go very far without ever reading a recipe.

Also I hear a lot about “opinionated guide” and such and I don’t really see that much opinion. Any documentation you write will have to deal with that everything is a total mess at the moment and not paper over it because that leads to significantly more confusion for those users.

fricklerhandwerk · May 14, 2023, 7:55am

I fully agree and was participating in some of those meetings, so my comment was really not to dismiss any of the work done. I think you’re doing a great job of sorting out the pile of tangled issues! It helps a lot that you now wrote down the current state of affairs here, because the pure discussion notes do not reveal what you were converging on.

With the 50LOC example I’m referring to what I see as a general tendency that you’re obviously fighting to avoid: to present a working sample one needs a lot of stuff which is incidental to the learning goal. The real value of these discussions will hopefully be an outcome that leads learners to full-fledged projects in small steps, as you say, and the critical piece is what to start with.

But yeah, overall my comment was not very productive…

fricklerhandwerk · May 14, 2023, 8:15am

This is simply not realistic due to how the system works in principle and, well, as you say, that it’s a mess. Apart from using ready-made packages and NixOS configurations you have to gain skills that are equivalent to being a contributor, and develop your own custom solutions. And that is also the user base that we need most, since the developer community is fairly small. Right now we don’t have the capacity to support users that can’t contribute or solve their own problems given some set of tools.

(If you manage to fund the project with $1M per year that might change in 2-3 years.)

That’s what we’re doing. I don’t know anyone who’s trying to paper over anything. The strategy that I’ve been following since the beginning was showing that the basics are really different from what one may be used to, but otherwise are very simple. Then there are layers of spaghetti on top, and apart from what can be explained concisely you’re on your own. We’re currently focusing on showing the simple bits and simply haven’t gotten to the „deal with it, sorry“ parts.

You’re warmly invited to make constructive proposals in the form of pull requests, especially if you disagree. Please take into account though that our capacity to do reviews is just as limited as for all the other work we do, so changes should always be incremental.

A very productive first step would be helping out by incorporating the answers to your questions into upstream. For instance, this discussion shows that we’re a bit behind on tracking our own rationale and intermediate results. Adding that to the relevant pages so the next person having an instinctive „but that’s wrong“ reaction can at least see what’s been done and why we arrived at particular conclusions before assuming feedback is not taken into account or no one is listening.

I can totally relate that you may be frustrated that things are not going as you imagine or wish for. The only way to change that is to contribute yourself.

alper · May 14, 2023, 8:52am

I think if you can convert thousands of users who just use this as a souped up homebrew, that’ll convert into more developers.

Here, I found this to be the most reasonable and clear/standalone explanation of what a derivation is and gave it a once over:

That’s kinda the level I’m at.

(Also just now realized that nix-shorts indeed proves my point that you can do a bunch of stuff without a nixlang tutorial.)

fricklerhandwerk · May 14, 2023, 12:27pm

That is probably true, and there is broad consensus that attracting users is the marketing team’s responsibility, while onboarding and retaining them is on the documentation team.

And that is all the problem is about: how are we supposed to retain developers if we can’t provide a consistent explanation of what’s going on? And how are we supposed to provide the explanation if no one really knows well enough to provide it concisely? I see the docs team’s job as tracking down the developer community’s shared understanding of the Nix ecosystem and phrasing it in a way people that who haven’t been exposed to it for multiple years can understand immediately. Note that it’s not even enough to just look at the source code, as the code doesn’t really understand or explain itself most of the time either.

I’m fully with you here, and that is why @Ericson2314 and me have invested a ridiculous amount if time to document fundamental Nix mechanisms without showing any code at all. Apart from even writing things down precisely enough to be correct but still brief enough not to be confusing as hell, the challenge here is really to get it upstream: these changes tend to be large in total, and maintainer capacity for reviews is an extremely scarce resource that we managed to expand only gradually in the past half year. The architecture section that has been merged is only a tiny part of what we’ve been working on, and it was quite exhausting to even get that landed.

And we specifically need upstream (“official”) documentation to be correct and useful, nothing else, because that is the only thing that can reasonably be maintained to stay up to date with the code and developers’ shared understanding (expressed by the code and documentation).

So, while I’m genuinely sorry if that sounds discouraging – it’s not intended. To the contrary I’m trying to paint a realistic picture to increase chances of success and satisfaction for everyone: while that type of work you did on Nix Shorts goes in the right direction, it neither satisfies your own didactic criteria (as it’s talking about attributes and other concepts that were not introduced beforehand) nor is it correct or precise enough to be acceptable as authoritative documentation (I see more issues than I can dump here), and most importantly it’s targeted at a third-party resource (which means it won’t be reviewed or kept up to date by Nix maintainers).

Some readers (@zmitchell @pxc @Dioprz @brianmcgee) will notice that I’m repeating myself, which may indicate I should write it down in a visible place somewhere.

Again, you’re warmly invited to participate in the development. I think we can all agree on what’s wrong. The interesting question is how to make it better in a way that can make it into upstream. Any help with that very much appreciated. Please make yourself familiar with what has been done, join the team meetings, make pull requests. Just don’t expect anything to go quickly.

zmitchell · May 14, 2023, 1:27pm

OK. Then go at it and don’t take any feedback from somebody who’s reasonably qualified.

I am taking your feedback, that’s why I took time out of my weekend to answer your questions and write you two small novels hoping to explain our mindset and rationale.

I think the outline posted above is pretty much the same as this?

There are similarities, but in content it won’t be the same.

Is the intention to improve on that or is this something separate?

The intention is to replace it.

Similar to how with homebrew you can go very far without ever reading a recipe.

I would love it if Nix was that easy, but homebrew and Nix are solving very different problems and Nix has much more functionality (e.g. you can’t write an OS on top of homebrew), so I think it’s unrealistic at this stage to expect the same ease of use for the entirety of the Nix feature set given the very limited maintainer capacity. Things could be easier, but making it so is not simple because it brings up design and implementation questions which then need to go through a lengthy review process.

Also I hear a lot about “opinionated guide” and such and I don’t really see that much opinion.

I agree “opinionated guide” is misleading. We’ve been in the process of transferring ownership and copyright to the NixOS Foundation to make nix.dev the official home of Nix documentation. That was very recently completed, and once it was completed I opened an issue (here) regarding this “opinionated guide” tagline.

Dioprz · May 14, 2023, 3:28pm

I feel quite identified with some of @alper’s comments. And I think we all have the same goals, but with different approaches. Despite this, and after soaking for several months in what @zmitchell and @fricklerhandwerk mention (as well as discussing and confronting it in multiple meetings) I must accept that the process of productively documenting a project of the size of Nix, and with so few resources, requires following some practical approaches that may not be of our preference.

Perhaps it all boils down, as @fricklerhandwerk mentions, to the fact that the documentation we must produce at this time is aimed at people who are experienced and autonomous in the management of their system, and who only need to understand how to approach it in order to discover its potential for themselves. This is the target, since this type of user is the one who:

Have greater skills and willingness to become contributors in the short/medium term.
Do not represent an overload for the contributors (neither nixpkgs, discourse, docs team, etc) since they are able, most of the time, to fend for themselves.

Although this reality is a bit sad since I myself feel “left out” of the target, it makes a lot of sense for the most immediate needs in documentation.

That said, and because I think the way of thinking I share with @alper will not cease to be a recurring theme in more and more people who come to Nix, I think it would be good for the team at some point to consider how to channel these efforts within the official documentation. Certainly people with technical skills are required to streamline the work and grow, but Nix is already a system quite capable of forming its own users, who although inexperienced, will be willing to grow within it and perhaps pay back in the long run being excellent contributors; and I think there are several people interested in creating material for them, but if there is no space to exploit those desires the trend to create guides and documentaicones not only continue, but unfortunately will grow.

Surely what is addressed in this discussion should be documented somewhere so that it is easier to digest the situation when wanting to contribute. Because I’m not sure where or how, I refrain from volunteering, but if I can be of help I’ll keep an eye out!

zmitchell · May 14, 2023, 4:35pm

Surely what is addressed in this discussion should be documented somewhere so that it is easier to digest the situation when wanting to contribute

Just so I understand, are you referring to the reasoning behind the particular tutorials we’ve chosen, the reason why the docs are the way they are right now, or something else?

If it’s the former I can think about a way to make a living “the current state of the tutorial series” document that gets updated along with the meeting notes. Past that I’m not sure if I’m the best person to write all that down or whether I have the additional time to collect all of that context/history.

alper · May 14, 2023, 5:22pm

OK. All good. Thanks for taking the time and I hope this wasn’t a waste of it.

alper · May 15, 2023, 8:00am

Not really required.

I’m just going ham on nix-shorts now forking it and updating it to be current and to use flakes. I think that should be really a fine starting point for a lot of people.

alper · May 20, 2023, 1:49pm

I mean I’ll admit that it is not great and could be improved a lot, but I didn’t want that to discourage me so I spent time forking and overhauling the entire set of shorts.

Just to put my time where my mouth is (and it took quite some more time than I expected):

If I get some (any?) positive feedback, I’ll continue pushing on this. If nothing else, it’s been a good way to capture and formalize my learning journey and structure the various bits and pieces I came across.

Dioprz · May 20, 2023, 8:45pm

Sorry for the delay in replying @zmitchell No, I’m talking about expressing the reasons why the documentation team is moving forward in general terms in producing more technical or advanced documentation. That will no doubt make it easier for new contributors looking to do something closer to Zero-to-Nix-style documentation to understand and empathize with the team’s limitations and projections.

@alper I only glanced at it, but I like the presentation of the ideas and the way you reference other sources of documentation (even if they are not official). I’ll keep an eye on your repository!